From c27fc5b91433d79867b9d8eb810376274096a5eb Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Thu, 3 Sep 2026 11:10:17 -0600 Subject: [PATCH 1/4] feat: add wild card functionality to knowledge store --- demo/AgentCore.Demo/config/example.yaml | 53 ++++- .../Schema/ProvidersConfiguration.cs | 35 ++- .../Schema/agentcore-v1.schema.json | 28 ++- .../Validation/ConfigurationValidator.cs | 115 ++++++++++ .../Configuration/Validation/StateDomain.cs | 13 +- src/AgentCore.Application/Diagnostics/Log.cs | 20 ++ .../Knowledge/KnowledgeAuditRecord.cs | 13 +- .../Knowledge/KnowledgePoint.cs | 2 +- .../Knowledge/KnowledgeProviderFactory.cs | 24 +- .../Knowledge/StateKnowledgeScope.cs | 87 ++++++++ .../PublicAPI.Unshipped.txt | 19 +- .../Runtime/CallSession.cs | 42 +++- .../Runtime/CallSessionFactory.cs | 3 +- .../Runtime/TurnAmbients.cs | 9 +- .../State/StateDocument.cs | 28 ++- .../Knowledge/KnowledgeCard.cs | 2 +- .../Knowledge/KnowledgeScope.cs | 21 ++ src/AgentCore.Domain/PublicAPI.Unshipped.txt | 6 + .../VectorData/Qdrant/IQdrantSearchChannel.cs | 15 +- .../Qdrant/QdrantKnowledgeAdapter.cs | 2 + .../VectorData/Qdrant/QdrantKnowledgeStore.cs | 86 +++++-- .../Qdrant/QdrantKnowledgeStoreOptions.cs | 9 +- .../VectorData/Qdrant/QdrantSearchChannel.cs | 3 +- .../KnowledgeProviderSchemaTests.cs | 5 +- .../Configuration/ConfigurationBinderTests.cs | 31 +++ .../Configuration/ConfigurationLoaderTests.cs | 2 +- .../Configuration/ExampleDocument.cs | 38 +++- .../Validation/ConfigurationValidatorTests.cs | 183 +++++++++++++++ .../Validation/StateDomainTests.cs | 45 ++++ .../Knowledge/KnowledgeAuditRecordTests.cs | 18 ++ .../KnowledgeProviderFactoryTests.cs | 113 ++++++++++ .../Knowledge/StateKnowledgeScopeTests.cs | 115 ++++++++++ .../Runtime/CallSessionTests.cs | 23 ++ .../KnowledgeScopeThroughCallSessionTests.cs | 211 +++++++++++++++++- .../State/StateDocumentTests.cs | 43 ++++ .../Knowledge/KnowledgeScopeTests.cs | 22 ++ .../Qdrant/Fakes/CapturingSearchChannel.cs | 4 +- .../Qdrant/Fakes/HangingSearchChannel.cs | 2 +- .../Qdrant/Fakes/RecordingSearchChannel.cs | 2 +- .../Qdrant/QdrantKnowledgeAdapterTests.cs | 24 ++ .../Qdrant/QdrantKnowledgeStoreTests.cs | 24 +- .../Qdrant/QdrantSearchChannelTests.cs | 4 +- .../Qdrant/QdrantWildcardScopeTests.cs | 158 +++++++++++++ .../Qdrant/ScoreFloorOnPrefetchTests.cs | 124 ++++++++++ .../Knowledge/VectorData/Qdrant/TestScopes.cs | 12 + .../Qdrant/WildcardScopeIntegrationTests.cs | 188 ++++++++++++++++ 46 files changed, 1954 insertions(+), 72 deletions(-) create mode 100644 src/AgentCore.Application/Knowledge/StateKnowledgeScope.cs create mode 100644 tests/AgentCore.Application.Tests/Configuration/Validation/StateDomainTests.cs create mode 100644 tests/AgentCore.Application.Tests/Knowledge/StateKnowledgeScopeTests.cs create mode 100644 tests/AgentCore.Domain.Tests/Knowledge/KnowledgeScopeTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantWildcardScopeTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ScoreFloorOnPrefetchTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/TestScopes.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/WildcardScopeIntegrationTests.cs diff --git a/demo/AgentCore.Demo/config/example.yaml b/demo/AgentCore.Demo/config/example.yaml index 03b1bdaf..57b09baf 100644 --- a/demo/AgentCore.Demo/config/example.yaml +++ b/demo/AgentCore.Demo/config/example.yaml @@ -49,6 +49,20 @@ state: # AgentCore coerces the value, and leaves the slot at its default when coercion fails. orderStatus: { type: string, writer: tool, from: lookup_order.status } + # writer: extractor, and also named in providers.knowledge.scope.fromState below, which is what + # turns these two into the turn's knowledge facets. A fromState slot has to be this exact shape — + # writer: extractor, type: string, an enum:, and no default — and the boot check says which of the + # four is missing rather than failing the load with no pointer. enum: is enforced on every write, + # not merely requested of the model: a value outside it is refused and the slot keeps its previous + # value, so a resumed call whose stored blob carries a value the corpus was never tagged with comes + # back with that slot unfilled rather than scoped to a typo. + # + # applies_to breaks this file's camelCase slot naming on purpose. A fromState slot name IS the + # facet key, and scope.template turns it straight into the payload path, so these two names have to + # be spelled the way the collection spells them rather than the way the schema spells its own keys. + brand: { type: string, writer: extractor, description: "The brand of the caller's machine.", enum: [sole, spirit] } + applies_to: { type: string, writer: extractor, description: "The model, as printed on the machine.", enum: [f63, f65, f80] } + # writer: counter. The slot increments whenever the increment rule is true. failedResolveTurns: type: integer @@ -322,10 +336,34 @@ providers: scope: template: "facets.{key}" - # How one facet key becomes a payload path. There is no default, because a template is a claim - # about where one collection keeps its facets. Flat facets are "{key}"; facets nested under one - # struct are "facets.{key}". Required as soon as ANY agent declares scoped: true — which is the - # default, so most documents need it. + # How one facet key becomes a payload path. There is no default, because a template is a claim + # about where one collection keeps its facets. Flat facets are "{key}"; facets nested under one + # struct are "facets.{key}". Required as soon as ANY agent declares scoped: true — which is the + # default, so most documents need it. + + wildcard: + value: "*" + facets: [brand, applies_to] + # How a card opts out of exact-match scoping, one facet at a time — never the whole scope. A + # card tagged facets.brand: "*" is reachable from a scope open on any brand, which is where + # opening hours, returns and warranty terms belong: they are true of no single machine. Name + # only the REACH facets here, and never an isolation facet such as a customer id — a wildcard + # on that would serve one mis-tagged card to every caller on every call, silently. The block is + # opt-in: leave it out and the emitted filter is byte-identical to a document that has never + # heard of it. + # + # Configure the wildcard first, and tag the corpus after. Re-tagging a company-wide card to + # facets.brand: "*" while this block is still absent means exact match keeps refusing it for + # the whole re-tag window; flipped first, the same tag starts working the moment it lands, and + # an untagged corpus answers exactly as it did before the block existed. + + fromState: [brand, applies_to] + # The state slots the turn's scope is built from, on top of whatever the host itself opens. + # Each name must point at a slot declared under state: above with writer: extractor, + # type: string, an enum:, and no default. A slot nothing has filled yet still appears in the + # scope, holding the wildcard, rather than being left out — leaving it out would put no + # condition on that facet at all, and every value of it would be in reach before the caller has + # said anything. links: field: see_also @@ -356,8 +394,11 @@ providers: # on the card, including fields no role above names. Registering under this same name replaces # the shipped wording for every agent without touching this document. - scoreFloor: 0.25 - # The smallest fused score a card may carry, 0 to 1. + scoreFloor: 0.35 + # The cosine similarity a card must score strictly above, 0 to 1. Qdrant applies it on the + # dense prefetch, so a question the corpus does not answer returns nothing instead of its three + # nearest cards. On text-embedding-3-small, 0.25 was too low to tell the two apart; 0.35 was not. + # 0 disables the floor. # mapper: my-mapper # An IKnowledgePointMapper registered with options.UseKnowledgePointMappers. Named, it owns the diff --git a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs index 817aa5a1..aee62aff 100644 --- a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs @@ -131,6 +131,26 @@ public sealed record KnowledgeScopeConfiguration /// 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 the state slots the turn's scope is built from. Each name becomes one facet key. + public IReadOnlyList FromState { 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. @@ -187,8 +207,13 @@ public sealed record KnowledgeProviderConfiguration /// The citation wording used when the document names none. public const string DefaultCitation = SourceLocatorCitationFormatter.FormatterName; - /// The score floor used when the document sets none. - public const double DefaultScoreFloor = 0.25; + /// + /// 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; } @@ -233,7 +258,11 @@ public sealed record KnowledgeProviderConfiguration public string? Mapper { get; init; } - /// Gets the smallest fused score a card may carry, in the range 0 to 1. + /// + /// 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; } diff --git a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json index 84308e05..7ccd50e8 100644 --- a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json +++ b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json @@ -1147,6 +1147,30 @@ "minLength": 1, "pattern": "\\{key\\}", "description": "The payload path each facet key becomes, with {key} standing for the key. Flat facets are {key}; facets nested under one struct are facets.{key}." + }, + "wildcard": { + "type": "object", + "description": "How a card marks itself reachable from every scope. Absent means exact match only.", + "additionalProperties": false, + "required": ["value", "facets"], + "properties": { + "value": { + "type": "string", + "minLength": 1, + "description": "The payload value that satisfies any scope on a named facet." + }, + "facets": { + "type": "array", + "minItems": 1, + "items": { "type": "string", "minLength": 1 }, + "description": "The facet keys the wildcard widens. Every other facet stays exact match." + } + } + }, + "fromState": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "description": "The state slots the turn's scope is built from. Each becomes one facet key." } } }, @@ -1199,8 +1223,8 @@ "type": "number", "minimum": 0, "maximum": 1, - "default": 0.25, - "description": "The smallest fused score a card may carry." + "default": 0.35, + "description": "The cosine similarity a card must score strictly above. Applied on the dense prefetch, before any fusion. 0 disables the floor." } } }, diff --git a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs index efdfe7d5..5d0a6c44 100644 --- a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs +++ b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs @@ -83,6 +83,7 @@ public static ConfigurationValidationResult EvaluateStructure(AgentCoreConfigura CheckReferences(configuration, names, errors); CheckSlotWriters(configuration, errors); + CheckKnowledgeScopeSlots(configuration, errors); CheckGuardRules(configuration, errors); CheckExclusivity(configuration, errors, warnings); CheckReachability(configuration, errors); @@ -498,6 +499,120 @@ private static void CheckMcpSecretPlacement(AgentCoreConfiguration configuration } } + // --------------------------------------------------------------------------------------------- + // Check 2, knowledge scope: a state-built scope must not produce a filter nobody meant. + // --------------------------------------------------------------------------------------------- + + /// Refuses a scope built from state that could 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. + /// + private static void CheckKnowledgeScopeSlots( + AgentCoreConfiguration configuration, List errors) + { + if (configuration.Providers?.Knowledge?.Scope is not { } scope) + { + return; + } + + if (scope.Wildcard is { } wildcard) + { + if (string.IsNullOrWhiteSpace(wildcard.Value)) + { + errors.Add(Reference( + "/providers/knowledge/scope/wildcard/value", + "the wildcard value is blank, so it names no payload value a card could carry.")); + } + + if (wildcard.Facets.Count == 0) + { + errors.Add(Reference( + "/providers/knowledge/scope/wildcard/facets", + "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.FromState.Count == 0) + { + return; + } + + if (scope.Wildcard is null) + { + errors.Add(Reference( + "/providers/knowledge/scope/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.")); + } + + 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 call searches only what the wildcard admits.")); + } + + foreach (var name in scope.FromState) + { + if (scope.Wildcard is { } declared + && !declared.Facets.Contains(name, StringComparer.Ordinal)) + { + errors.Add(Reference( + "/providers/knowledge/scope/wildcard/facets", + $"fromState names '{name}' and wildcard.facets does not, so an unfilled '{name}' " + + "would be searched for the literal wildcard rather than widened by it.")); + } + + if (!configuration.State.TryGetValue(name, out var slot)) + { + errors.Add(Reference( + "/providers/knowledge/scope/fromState", + $"fromState names the slot '{name}', which this document does not declare.")); + continue; + } + + var pointer = Pointer.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 call 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.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-call.")); + } + + 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.")); + } + } + } + // --------------------------------------------------------------------------------------------- // Check 3: one writer for each slot. // --------------------------------------------------------------------------------------------- diff --git a/src/AgentCore.Application/Configuration/Validation/StateDomain.cs b/src/AgentCore.Application/Configuration/Validation/StateDomain.cs index bd7a1719..f7f879c3 100644 --- a/src/AgentCore.Application/Configuration/Validation/StateDomain.cs +++ b/src/AgentCore.Application/Configuration/Validation/StateDomain.cs @@ -193,9 +193,18 @@ public static string Describe(IReadOnlyDictionary state) slot = reserved; } - if (slot.EnumValues is { Count: > 0 }) + if (slot.EnumValues is { Count: > 0 } members) { - return [.. slot.EnumValues.Select(static member => (JsonNode?)member.DeepClone())]; + 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 call never starts in. + if (slot.Default is null) + { + points.Add(null); + } + + return points; } return slot.Type switch diff --git a/src/AgentCore.Application/Diagnostics/Log.cs b/src/AgentCore.Application/Diagnostics/Log.cs index f947579d..2f0d504f 100644 --- a/src/AgentCore.Application/Diagnostics/Log.cs +++ b/src/AgentCore.Application/Diagnostics/Log.cs @@ -1,4 +1,5 @@ using AgentCore.Application.Knowledge; +using AgentCore.Domain.Knowledge; using Microsoft.Extensions.Logging; namespace AgentCore.Application.Diagnostics; @@ -171,4 +172,23 @@ public static partial void KnowledgeRetrievalFailed( Message = "An edit withdrew call {CallId} from ordinal {FromOrdinal} onward, " + "at turn {TurnIndex}.")] public static partial void CallTruncated(ILogger logger, string callId, 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 call. + /// The zero-based index of the turn. + /// Where each facet's value came from. + [LoggerMessage( + EventId = 15, + Level = LogLevel.Debug, + Message = "Call {CallId} turn {TurnIndex} composed the knowledge scope {Origins}.")] + public static partial void KnowledgeScopeComposed( + ILogger logger, + string callId, + int turnIndex, + IReadOnlyDictionary origins); } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeAuditRecord.cs b/src/AgentCore.Application/Knowledge/KnowledgeAuditRecord.cs index 961323aa..7bac2fe1 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeAuditRecord.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeAuditRecord.cs @@ -11,6 +11,9 @@ 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; } @@ -26,6 +29,9 @@ internal sealed record KnowledgeAuditRecord /// 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; } @@ -57,6 +63,7 @@ public static KnowledgeAuditRecord For( Mode = mode, Query = query, Scope = scope?.Facets ?? EmptyScope, + ScopeOrigins = scope?.Origins ?? EmptyOrigins, LatencyMs = latencyMs, Cards = [.. cards.Select(CardEntry.For)], Failure = failure?.ToString(), @@ -72,6 +79,7 @@ public static KnowledgeAuditRecord For( Mode = Mode, QueryLength = Query.Length, Scope = Scope, + ScopeOrigins = ScopeOrigins, LatencyMs = LatencyMs, Cards = Cards, }; @@ -96,6 +104,9 @@ internal sealed record LogView /// 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; } @@ -109,7 +120,7 @@ internal sealed record CardEntry /// Gets the card id. public required string CardId { get; init; } - /// Gets the fused score, or when a link pulled the card in. + /// 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. diff --git a/src/AgentCore.Application/Knowledge/KnowledgePoint.cs b/src/AgentCore.Application/Knowledge/KnowledgePoint.cs index 5573fdee..b7875dde 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgePoint.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgePoint.cs @@ -6,7 +6,7 @@ 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 fused score, or when the point was fetched rather than ranked. + /// 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. diff --git a/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs b/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs index 72d92865..da9e1f01 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs @@ -29,6 +29,19 @@ internal static class KnowledgeProviderFactory "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 call by announcing an empty knowledge base. + /// + private const string EmptyNotice = + "The knowledge base holds nothing for this question. Say so, and do not answer from memory."; + + /// The source name every notice carries, so the model can never cite one as a card. + internal const string NoticeSourceName = "agentcore:notice"; + /// /// The scope an agent that declares scoped: false searches under. /// @@ -103,6 +116,15 @@ internal static AIContextProvider Create( Log.KnowledgeRetrieved(logger, agent, cards.Count, record); } + // Only a scope with at least one facet gets the notice. An unscoped agent opened + // WholeCorpus, and its empty search stays an empty list. + if (cards.Count == 0 + && knowledge.Mode == KnowledgeMode.Tool + && KnowledgeScopeScope.Current is { Facets.Count: > 0 }) + { + return [Notice(EmptyNotice)]; + } + var shown = Kept(cards, knowledge); Cite(shown, knowledge, citations); @@ -217,5 +239,5 @@ private static List Kept(IReadOnlyList cards, Reso /// What the model is told. /// The result. private static TextSearchProvider.TextSearchResult Notice(string text) - => new() { Text = text }; + => new() { Text = text, SourceName = NoticeSourceName }; } diff --git a/src/AgentCore.Application/Knowledge/StateKnowledgeScope.cs b/src/AgentCore.Application/Knowledge/StateKnowledgeScope.cs new file mode 100644 index 00000000..d4ea3092 --- /dev/null +++ b/src/AgentCore.Application/Knowledge/StateKnowledgeScope.cs @@ -0,0 +1,87 @@ +using System.Text.Json.Nodes; +using AgentCore.Application.Configuration.Schema; +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 +{ + /// Composes the turn's scope from the host's ambient and the call's state. + /// The state of the call, as it stands at the start of this turn. + /// The document's providers.knowledge.scope block, or null. + /// What the host opened for this turn, or null when it opened nothing. + /// The scope, or unchanged when this document composes none. + internal static KnowledgeScope? Compose( + StateDocument state, KnowledgeScopeConfiguration? scope, KnowledgeScope? ambient) + { + 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) + { + return ambient; + } + + Dictionary facets = new(StringComparer.Ordinal); + Dictionary origins = new(StringComparer.Ordinal); + + if (ambient is not null) + { + foreach (var (key, value) in ambient.Facets) + { + facets[key] = value; + origins[key] = KnowledgeFacetOrigin.Host; + } + } + + foreach (var slot in scope.FromState) + { + 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 }; + } + + /// 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)) + { + return null; + } + + return state.Read(slot) is JsonValue value + && value.TryGetValue(out string? text) + && !string.IsNullOrWhiteSpace(text) + ? text + : null; + } +} diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index deaff9c4..506ae994 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -480,9 +480,21 @@ AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.Vector AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.$() -> AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration! AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.Equals(AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration? other) -> bool +AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.FromState.get -> System.Collections.Generic.IReadOnlyList! +AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.FromState.init -> void AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.KnowledgeScopeConfiguration() -> void AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.Template.get -> string? AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.Template.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.Wildcard.get -> AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration? +AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.Wildcard.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration +AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.$() -> AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration! +AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.Equals(AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration? other) -> bool +AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.Facets.get -> System.Collections.Generic.IReadOnlyList! +AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.Facets.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.KnowledgeWildcardConfiguration() -> void +AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.Value.get -> string! +AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.Value.init -> void AgentCore.Application.Configuration.Schema.LlmProviderConfiguration AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.$() -> AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.As.get -> string! @@ -1186,7 +1198,7 @@ const AgentCore.Application.Configuration.Schema.EvaluationConfiguration.Default const AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.DefaultNamespace = "url" -> string! const AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.DefaultAnalyzer = "none" -> string! const AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.DefaultCitation = "source-locator" -> string! -const AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.DefaultScoreFloor = 0.25 -> double +const AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.DefaultScoreFloor = 0.35 -> double const AgentCore.Application.Configuration.Schema.ReservedStateSlots.CallDurationSeconds = "callDurationSeconds" -> string! const AgentCore.Application.Configuration.Schema.ReservedStateSlots.Stage = "stage" -> string! const AgentCore.Application.Configuration.Schema.ReservedStateSlots.TurnIndex = "turnIndex" -> string! @@ -1323,6 +1335,9 @@ override AgentCore.Application.Configuration.Schema.KnowledgeProviderConfigurati override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.GetHashCode() -> int override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.ToString() -> string! override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.GetHashCode() -> int override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.ToString() -> string! @@ -1505,6 +1520,8 @@ static AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration static AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.operator !=(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration? left, AgentCore.Application.Configuration.Schema.LlmProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.operator ==(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration? left, AgentCore.Application.Configuration.Schema.LlmProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.McpAllowEntry.operator !=(AgentCore.Application.Configuration.Schema.McpAllowEntry? left, AgentCore.Application.Configuration.Schema.McpAllowEntry? right) -> bool diff --git a/src/AgentCore.Application/Runtime/CallSession.cs b/src/AgentCore.Application/Runtime/CallSession.cs index b77f7548..0d5aced2 100644 --- a/src/AgentCore.Application/Runtime/CallSession.cs +++ b/src/AgentCore.Application/Runtime/CallSession.cs @@ -6,6 +6,7 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; using AgentCore.Application.Diagnostics; +using AgentCore.Application.Knowledge; using AgentCore.Application.Policy; using AgentCore.Application.Ports; using AgentCore.Application.State; @@ -13,8 +14,11 @@ using AgentCore.Application.Transcript; using AgentCore.Domain; using AgentCore.Domain.Audit; +using AgentCore.Domain.Knowledge; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging.Abstractions; namespace AgentCore.Application.Runtime; @@ -76,6 +80,8 @@ public sealed class CallSession : IConversationPort private readonly bool _sessionCarriesHistory; + private readonly ILogger _logger; + private readonly Lock _interruptLock = new(); private AgentSession? _agentSession; @@ -113,7 +119,8 @@ internal CallSession( IGuardEvaluator guards, StateExtractor? extractor, TimeProvider timeProvider, - CallObserverDispatcher? observers = null) + CallObserverDispatcher? observers = null, + ILogger? logger = null) { ArgumentException.ThrowIfNullOrEmpty(callId); ArgumentNullException.ThrowIfNull(compiled); @@ -122,6 +129,8 @@ internal CallSession( CallId = callId; + _logger = logger ?? NullLogger.Instance; + _compiled = compiled; _history = compiled.History; @@ -683,7 +692,8 @@ private IDisposable EnterAmbients(Turn turn) turn.Renders, turn.Sources, failure => _events.RaiseToolFailure(turn.Index, failure), - TurnContextOf(turn)); + TurnContextOf(turn), + turn.Knowledge); /// /// Reads what one turn adds to its own model invocation. @@ -779,6 +789,15 @@ private Turn BeginTurn(string userInput, AgentSession session, CallTurnOrigin? o // One turn is one span. The call 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. var activity = AgentCoreTelemetry.StartTurn(CallId, State.TurnIndex, State.Stage); + + var knowledge = StateKnowledgeScope.Compose( + State, _compiled.Configuration.Providers?.Knowledge?.Scope, KnowledgeScopeScope.Current); + + if (knowledge is { Origins.Count: > 0 }) + { + Log.KnowledgeScopeComposed(_logger, CallId, State.TurnIndex, knowledge.Origins); + } + return new Turn( agent, session, @@ -791,6 +810,7 @@ private Turn BeginTurn(string userInput, AgentSession session, CallTurnOrigin? o _time.GetTimestamp(), _hasScreen ? new TurnRenders() : null, new TurnSources(), + knowledge, origin?.MessageId); } @@ -1233,9 +1253,17 @@ private async Task CompleteTurnAsync( return null; } - // The extractor reads one finished turn and not the whole call, which is what its own prompt - // asks for. The state document already carries every earlier answer, so nothing is lost. + // 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 call 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 (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 _extractor.ExtractAsync(State, finished, cancellationToken).ConfigureAwait(false); @@ -1311,6 +1339,11 @@ private AIAgent ResolveAgent() /// What this turn cites into. Built once per turn for the same reason is, /// and never null: a call with no screen still answers from documents. /// + /// + /// What this turn may see of the knowledge base. Built once per turn for the same reason + /// is, and additionally because a scope that changed between two updates + /// of one streaming turn would search two different corpora for one answer. + /// /// /// What the caller calls the message it sent, or when it named none. The /// append stamps it on the row so a later edit has something to anchor on. @@ -1327,6 +1360,7 @@ private sealed record Turn( long StartedAt, TurnRenders? Renders, TurnSources Sources, + KnowledgeScope? Knowledge, string? MessageId); /// The session a graph row's call holds, so store 1 has somewhere to live. diff --git a/src/AgentCore.Application/Runtime/CallSessionFactory.cs b/src/AgentCore.Application/Runtime/CallSessionFactory.cs index 5c160369..6389a42d 100644 --- a/src/AgentCore.Application/Runtime/CallSessionFactory.cs +++ b/src/AgentCore.Application/Runtime/CallSessionFactory.cs @@ -78,7 +78,8 @@ public CallSession Create(string? callId = null, CallSessionState? state = null) _guards, _extractor, _time, - new CallObserverDispatcher(_observers, _logger)); + new CallObserverDispatcher(_observers, _logger), + _logger); // Named, not applied. The session resumes on its first turn, where store 0's own copy // outranks this one — see the remarks on CallSession.Resume. diff --git a/src/AgentCore.Application/Runtime/TurnAmbients.cs b/src/AgentCore.Application/Runtime/TurnAmbients.cs index 783befdc..fa11c639 100644 --- a/src/AgentCore.Application/Runtime/TurnAmbients.cs +++ b/src/AgentCore.Application/Runtime/TurnAmbients.cs @@ -46,19 +46,23 @@ internal sealed record TurnAmbients /// What this turn cites into. Never null: a call with no screen still has sources. /// What to do with a tool failure the run reports. /// The turn the tools are running inside. + /// What this turn may see of the knowledge base, or when the document composes none. internal static IDisposable Enter( StateDocument state, TurnRenders? renders, TurnSources sources, Action onToolFailure, - TurnContext context) + TurnContext context, + KnowledgeScope? knowledge) { ArgumentNullException.ThrowIfNull(state); ArgumentNullException.ThrowIfNull(sources); ArgumentNullException.ThrowIfNull(onToolFailure); ArgumentNullException.ThrowIfNull(context); - return Push((Ambient.Value ?? None) with + var current = Ambient.Value ?? None; + + return Push(current with { State = state, Screen = renders, @@ -66,6 +70,7 @@ internal static IDisposable Enter( Sources = sources, OnToolFailure = onToolFailure, Context = context, + Knowledge = knowledge ?? current.Knowledge, }); } diff --git a/src/AgentCore.Application/State/StateDocument.cs b/src/AgentCore.Application/State/StateDocument.cs index 0717c6d1..424c8eed 100644 --- a/src/AgentCore.Application/State/StateDocument.cs +++ b/src/AgentCore.Application/State/StateDocument.cs @@ -94,7 +94,8 @@ public bool IsUnfilled(string slot) /// The raw value the writer produced. /// /// when the value coerced and the slot changed. - /// when coercion failed, which leaves the slot at its default. + /// 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) @@ -116,10 +117,35 @@ public bool TryWrite(string slot, JsonNode? value) 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; } + // 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(); + + foreach (var member in members) + { + if (string.Equals(member.ToJsonString(), written, StringComparison.Ordinal)) + { + return true; + } + } + + return false; + } + /// 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() diff --git a/src/AgentCore.Domain/Knowledge/KnowledgeCard.cs b/src/AgentCore.Domain/Knowledge/KnowledgeCard.cs index 42bc1fa9..f65ae97c 100644 --- a/src/AgentCore.Domain/Knowledge/KnowledgeCard.cs +++ b/src/AgentCore.Domain/Knowledge/KnowledgeCard.cs @@ -28,7 +28,7 @@ public sealed record KnowledgeCard /// Gets how much the source is trusted: higher is more trusted. public int? Authority { get; init; } - /// Gets the fused score, or when a link pulled this card in. + /// 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; } /// diff --git a/src/AgentCore.Domain/Knowledge/KnowledgeScope.cs b/src/AgentCore.Domain/Knowledge/KnowledgeScope.cs index b7d99b34..6506a42f 100644 --- a/src/AgentCore.Domain/Knowledge/KnowledgeScope.cs +++ b/src/AgentCore.Domain/Knowledge/KnowledgeScope.cs @@ -1,10 +1,31 @@ namespace AgentCore.Domain.Knowledge; +/// Where one facet's value came from. +public enum KnowledgeFacetOrigin +{ + /// The host resolved it and opened it on the turn. + Host, + + /// The extractor read it out of what the caller said. + Extractor, + + /// 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; } + + /// + /// 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/PublicAPI.Unshipped.txt b/src/AgentCore.Domain/PublicAPI.Unshipped.txt index 1e6e2e4b..420f9225 100644 --- a/src/AgentCore.Domain/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Domain/PublicAPI.Unshipped.txt @@ -62,12 +62,18 @@ AgentCore.Domain.Knowledge.KnowledgeCard.Text.get -> string! AgentCore.Domain.Knowledge.KnowledgeCard.Text.init -> void AgentCore.Domain.Knowledge.KnowledgeCard.ViaLink.get -> bool AgentCore.Domain.Knowledge.KnowledgeCard.ViaLink.init -> void +AgentCore.Domain.Knowledge.KnowledgeFacetOrigin +AgentCore.Domain.Knowledge.KnowledgeFacetOrigin.Extractor = 1 -> AgentCore.Domain.Knowledge.KnowledgeFacetOrigin +AgentCore.Domain.Knowledge.KnowledgeFacetOrigin.Host = 0 -> AgentCore.Domain.Knowledge.KnowledgeFacetOrigin +AgentCore.Domain.Knowledge.KnowledgeFacetOrigin.Wildcard = 2 -> AgentCore.Domain.Knowledge.KnowledgeFacetOrigin AgentCore.Domain.Knowledge.KnowledgeScope AgentCore.Domain.Knowledge.KnowledgeScope.$() -> AgentCore.Domain.Knowledge.KnowledgeScope! AgentCore.Domain.Knowledge.KnowledgeScope.Equals(AgentCore.Domain.Knowledge.KnowledgeScope? other) -> bool AgentCore.Domain.Knowledge.KnowledgeScope.Facets.get -> System.Collections.Generic.IReadOnlyDictionary! AgentCore.Domain.Knowledge.KnowledgeScope.Facets.init -> void AgentCore.Domain.Knowledge.KnowledgeScope.KnowledgeScope() -> void +AgentCore.Domain.Knowledge.KnowledgeScope.Origins.get -> System.Collections.Generic.IReadOnlyDictionary! +AgentCore.Domain.Knowledge.KnowledgeScope.Origins.init -> void AgentCore.Domain.Sources.SourceKind AgentCore.Domain.Sources.SourceKind.Document = 0 -> AgentCore.Domain.Sources.SourceKind AgentCore.Domain.Sources.SourceKind.Url = 1 -> AgentCore.Domain.Sources.SourceKind diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs index b3df9774..f49b6271 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs @@ -2,13 +2,14 @@ namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; -/// One fused query, ready to send. +/// One query, ready to send. /// The collection, always an alias. -/// The prefetch legs the fusion combines. -/// The fusion itself. -/// How many fused results to return. -internal sealed record FusedQuery( - string Collection, IReadOnlyList Prefetch, Query Query, ulong Limit); +/// 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. @@ -19,7 +20,7 @@ internal interface IQdrantSearchChannel /// The query. /// Cancels the call. The store links its deadline into this. /// The scored points, best first. - Task> QueryAsync(FusedQuery query, CancellationToken cancellationToken); + Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken); /// Fetches whole points by key, in one call. /// The collection. diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapter.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapter.cs index 726f69cc..39d70446 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapter.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapter.cs @@ -263,6 +263,8 @@ public async ValueTask CreateSearchAsync( 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, diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs index d7127e45..6e22c6de 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs @@ -110,11 +110,9 @@ public async ValueTask> SearchAsync( var points = await _channel .QueryAsync(BuildQuery(query, embedding.Vector, scope), deadline.Token).ConfigureAwait(false); - var ranked = points.Where(point => point.Score >= _options.ScoreFloor).ToList(); - List cards = []; - foreach (var point in ranked) + foreach (var point in points) { if (Map(point.Id, point.Payload, point.Score, viaLink: false) is { } card) { @@ -122,7 +120,7 @@ public async ValueTask> SearchAsync( } } - if (ranked.Count == 0 || _options.Links is not { } linksConfiguration) + if (points.Count == 0 || _options.Links is not { } linksConfiguration) { return cards; } @@ -130,7 +128,7 @@ public async ValueTask> SearchAsync( var 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(ranked[0].Payload, linksConfiguration.Field!) + var links = QdrantPayload.ReadList(points[0].Payload, linksConfiguration.Field!) .Where(id => !have.Contains(id)) .Distinct(StringComparer.Ordinal) .ToList(); @@ -152,7 +150,7 @@ public async ValueTask> SearchAsync( return cards; } - private FusedQuery BuildQuery(string query, ReadOnlyMemory vector, KnowledgeScope? scope) + private SearchQuery BuildQuery(string query, ReadOnlyMemory vector, KnowledgeScope? scope) { var scopeFilter = new Filter(); foreach (var (facet, value) in Facets(scope)) @@ -163,7 +161,7 @@ private FusedQuery BuildQuery(string query, ReadOnlyMemory vector, Knowle // 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 = ScopePath(facet), Match = new Match { Keyword = value } }, + Field = new FieldCondition { Key = ScopePath(facet), Match = MatchFor(facet, value) }, }); } @@ -193,8 +191,49 @@ private FusedQuery BuildQuery(string query, ReadOnlyMemory vector, Knowle } } - return new FusedQuery( - _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); + } + + /// 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 [value]; + } + + return [.. new[] { value, wildcard }.Order(StringComparer.Ordinal)]; + } + + /// + /// Builds the match one facet condition carries. + /// + /// + /// 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. + /// + private Match MatchFor(string facet, string value) + { + var values = Values(facet, value); + + return values.Count == 1 + ? new Match { Keyword = values[0] } + : new Match { Keywords = new RepeatedStrings { Strings = { values } } }; } private static IEnumerable> Facets(KnowledgeScope? scope) => @@ -212,8 +251,19 @@ private PrefetchQuery Dense(ReadOnlyMemory vector, Filter filter, ulong d }, }; + // 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 (_options.VectorName is { Length: > 0 } name) + if (VectorName is { } name) { leg.Using = name; } @@ -221,6 +271,13 @@ private PrefetchQuery Dense(ReadOnlyMemory vector, Filter filter, ulong d 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; + /// Fetches the cards a link named, under this deployment's lookup mode. private Task> FetchLinkedAsync( KnowledgeLinksConfiguration links, List ids, CancellationToken cancellationToken) @@ -258,7 +315,8 @@ private Task> FetchLinkedAsync( /// Whether a card the ranking never chose is still inside the turn's scope. private bool InScope(MapField payload, KnowledgeScope? scope) => - Facets(scope).All(entry => Holds(QdrantPayload.Read(payload, ScopePath(entry.Key)), entry.Value)); + Facets(scope).All(entry => + Holds(QdrantPayload.Read(payload, ScopePath(entry.Key)), Values(entry.Key, entry.Value))); /// Turns one facet key into the payload path this collection keeps it at. /// @@ -274,12 +332,12 @@ private string ScopePath(string facet) + "default. Write scope.template, such as '{key}' for flat facets."); /// Mirrors Qdrant keyword matching, where a list facet matches when any element does. - private static bool Holds(Value? facet, string wanted) => facet switch + private static bool Holds(Value? facet, IReadOnlyList wanted) => facet switch { { KindCase: Value.KindOneofCase.StringValue } value => - string.Equals(value.StringValue, wanted, StringComparison.Ordinal), + wanted.Contains(value.StringValue, StringComparer.Ordinal), { KindCase: Value.KindOneofCase.ListValue } value => - value.ListValue.Values.Any(item => string.Equals(item.StringValue, wanted, StringComparison.Ordinal)), + value.ListValue.Values.Any(item => wanted.Contains(item.StringValue, StringComparer.Ordinal)), _ => false, }; diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreOptions.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreOptions.cs index 41eb4a83..44a74736 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreOptions.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreOptions.cs @@ -28,6 +28,12 @@ internal sealed record QdrantKnowledgeStoreOptions /// 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 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; } @@ -41,7 +47,8 @@ internal sealed record QdrantKnowledgeStoreOptions public int Limit { get; init; } = 5; /// - /// Gets the smallest fused score a card may carry, in the range 0 to 1. + /// 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; diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs index 913af108..f891f41b 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs @@ -21,7 +21,7 @@ public QdrantSearchChannel(QdrantClient client) public void Dispose() => _client.Dispose(); /// - public Task> QueryAsync(FusedQuery query, CancellationToken cancellationToken) + public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) { ArgumentNullException.ThrowIfNull(query); @@ -30,6 +30,7 @@ public Task> QueryAsync(FusedQuery query, Cancellatio query.Collection, prefetch: query.Prefetch, query: query.Query, + usingVector: query.Using, limit: query.Limit, payloadSelector: new WithPayloadSelector { Enable = true }, cancellationToken: cancellationToken), diff --git a/tests/AgentCore.Application.Tests/Compilation/KnowledgeProviderSchemaTests.cs b/tests/AgentCore.Application.Tests/Compilation/KnowledgeProviderSchemaTests.cs index ded5b7b0..c0b717cf 100644 --- a/tests/AgentCore.Application.Tests/Compilation/KnowledgeProviderSchemaTests.cs +++ b/tests/AgentCore.Application.Tests/Compilation/KnowledgeProviderSchemaTests.cs @@ -102,7 +102,10 @@ public void ABlockThatNamesNoFields_MapsNothing() // 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); - Assert.Equal(0.25, knowledge.ScoreFloor); + // 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] diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs index 79aa7131..bcfb1cca 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs @@ -226,4 +226,35 @@ public void Bind_ASkillNameOutsideMafsCharset_FailsCheckOne(string name) Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); } + + [Fact] + public void Bind_KnowledgeScopeWildcardAndFromState_ReadsBoth() + { + const string Document = """ + apiVersion: agentcore/v1 + name: doc + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + wildcard: + value: "*" + facets: [brand, applies_to] + fromState: [brand, applies_to] + """; + + var configuration = ConfigurationLoader.LoadYaml(Document); + var 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); + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs index 2d3d706e..b1c74f80 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs @@ -22,7 +22,7 @@ public void Example_CarriesTheDocumentHeader() [Fact] public void Example_BindsEveryStateSlot() { - Assert.Equal(6, Example.State.Count); + Assert.Equal(8, Example.State.Count); var goodbye = Example.State["callerSaidGoodbye"]; Assert.Equal(StateSlotType.Boolean, goodbye.Type); diff --git a/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs b/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs index d400789e..8f689996 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs @@ -45,6 +45,8 @@ internal static class ExampleDocument machineIdentified: { type: boolean, default: false, writer: extractor } resolved: { type: boolean, default: false, writer: extractor } orderStatus: { type: string, writer: tool, from: lookup_order.status } + brand: { type: string, writer: extractor, description: "The brand of the caller's machine.", enum: [sole, spirit] } + applies_to: { type: string, writer: extractor, description: "The model, as printed on the machine.", enum: [f63, f65, f80] } failedResolveTurns: type: integer default: 0 @@ -175,6 +177,10 @@ internal static class ExampleDocument authority: authority scope: template: "facets.{key}" + wildcard: + value: "*" + facets: [brand, applies_to] + fromState: [brand, applies_to] links: field: see_also lookup: uuid5 @@ -221,6 +227,25 @@ internal static class ExampleDocument "writer": "tool", "from": "lookup_order.status" }, + "brand": { + "type": "string", + "writer": "extractor", + "description": "The brand of the caller's machine.", + "enum": [ + "sole", + "spirit" + ] + }, + "applies_to": { + "type": "string", + "writer": "extractor", + "description": "The model, as printed on the machine.", + "enum": [ + "f63", + "f65", + "f80" + ] + }, "failedResolveTurns": { "type": "integer", "default": 0, @@ -574,7 +599,18 @@ internal static class ExampleDocument "authority": "authority" }, "scope": { - "template": "facets.{key}" + "template": "facets.{key}", + "wildcard": { + "value": "*", + "facets": [ + "brand", + "applies_to" + ] + }, + "fromState": [ + "brand", + "applies_to" + ] }, "links": { "field": "see_also", diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs index 38c1a22f..01dc67aa 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs @@ -1,4 +1,5 @@ using System.Text; +using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Configuration.Validation; @@ -335,6 +336,188 @@ public void TwoMcpEntriesSharingAnId_FailCheckTwoNamingTheId() 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 CallSession 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) => new() + { + ApiVersion = "agentcore/v1", + Name = "doc", + State = new Dictionary(state, StringComparer.Ordinal), + Extractor = extractor, + Providers = new() + { + Knowledge = new() + { + Kind = "qdrant", + Collection = "kb", + Fields = new() { Body = "text" }, + Scope = new() + { + Template = "facets.{key}", + Wildcard = wildcard, + FromState = fromState, + }, + }, + }, + }; + + private static StateSlotConfiguration FacetSlot() => new() + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + EnumValues = [JsonValue.Create("f63")!], + }; + + private static readonly KnowledgeWildcardConfiguration Star = + new() { Value = "*", Facets = ["applies_to"] }; + + private static ExtractorConfiguration AnExtractor() => + new() { Model = new ModelReference { Ref = "small" } }; + + [Fact] + public void Evaluate_FromStateNamesAnUndeclaredSlot_Fails() + { + var result = ConfigurationValidator.EvaluateStructure( + Scoped(["applies_to"], Star, new Dictionary(), AnExtractor())); + + var error = Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/fromState"); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void Evaluate_FacetSlotDeclaresADefault_Fails() + { + var slot = FacetSlot() with { Default = JsonValue.Create("f63") }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor())); + + Assert.Single(result.Errors, e => e.Pointer == "/state/applies_to/default"); + } + + [Fact] + public void Evaluate_FromStateWithoutAWildcard_Fails() + { + var 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"); + } + + [Fact] + public void Evaluate_FacetSlotIsNotTypeString_Fails() + { + var slot = FacetSlot() with { Type = StateSlotType.Boolean }; + + var 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); + } + + [Fact] + public void Evaluate_FacetSlotIsNotWrittenByExtractor_Fails() + { + var slot = FacetSlot() with { Writer = StateWriter.Const, Value = JsonValue.Create("f63") }; + + var 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/writer"); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void Evaluate_FacetSlotDeclaresNoEnum_Fails() + { + var slot = FacetSlot() with { EnumValues = null }; + + var 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/enum"); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void Evaluate_FromStateWithNoExtractor_Fails() + { + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() })); + + Assert.Single(result.Errors, e => e.Pointer == "/extractor"); + } + + [Fact] + public void Evaluate_FromStateNameNotInWildcardFacets_Fails() + { + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["other_facet"] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + wildcard, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor())); + + 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_FacetWildcardValueIsWhitespace_Fails() + { + var wildcard = new KnowledgeWildcardConfiguration { Value = " ", Facets = ["applies_to"] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped([], wildcard, new Dictionary())); + + Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/value"); + } + + [Fact] + public void Evaluate_FacetWildcardDeclaresNoFacets_Fails() + { + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = [] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped([], wildcard, new Dictionary())); + + Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/facets"); + } + // --------------------------------------------------------------------------------------------- // Check 3: one writer for each slot. // --------------------------------------------------------------------------------------------- diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/StateDomainTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/StateDomainTests.cs new file mode 100644 index 00000000..89d7b959 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/StateDomainTests.cs @@ -0,0 +1,45 @@ +using System.Text.Json.Nodes; +using AgentCore.Application.Configuration.Schema; +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 +{ + [Fact] + public void Points_EnumSlotWithNoDefault_IncludesTheUnfilledPoint() + { + AgentCoreConfiguration configuration = new() + { + ApiVersion = "agentcore/v1", + Name = "doc", + State = new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = new() + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + EnumValues = [JsonValue.Create("f63")!, JsonValue.Create("f65")!], + }, + }, + }; + + var points = Points(configuration, "applies_to"); + + 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 }); + + var 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/Knowledge/KnowledgeAuditRecordTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeAuditRecordTests.cs index 545b289f..34f09f94 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeAuditRecordTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeAuditRecordTests.cs @@ -104,6 +104,24 @@ public void CardEntry_CardWithNoAuthorityOrSource_RecordsNulls() Assert.Equal("ranked", entry.Via); } + [Fact] + public void For_CarriesTheScopeOrigins() + { + KnowledgeScope scope = new() + { + Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "*" }, + Origins = new Dictionary(StringComparer.Ordinal) + { + ["brand"] = KnowledgeFacetOrigin.Wildcard, + }, + }; + + var record = KnowledgeAuditRecord.For( + null, "agent", KnowledgeMode.Tool, "q", scope, [], 1.0, null); + + Assert.Equal(KnowledgeFacetOrigin.Wildcard, record.ScopeOrigins["brand"]); + } + private static KnowledgeScope Scope() => new() { Facets = new Dictionary { ["model"] = "ct900" } }; diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs index e3dc5142..f6030d7c 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs @@ -1,3 +1,4 @@ +using System.Reflection; using System.Text.Json; using AgentCore.TestSupport; using AgentCore.Application.Configuration.Compilation; @@ -604,6 +605,79 @@ await provider.InvokingAsync( Assert.Contains("does it need a part?", port.LastQuery!, StringComparison.Ordinal); } + [Fact] + public async Task Search_ToolModeWithNoResults_InjectsTheEmptyNotice() + { + var provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Tool, scoped: true)); + using var open = KnowledgeScopeScope.Open( + new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }); + + var results = await InvokeSearchAsync(provider, "f63 error e03"); + + Assert.Contains(results, r => r.Text.Contains("holds nothing", StringComparison.Ordinal)); + } + + [Fact] + public async Task Search_PrefetchModeWithNoResults_InjectsNothing() + { + var provider = Provider(new StubKnowledgePort([]), Resolved(KnowledgeMode.Prefetch)); + + var results = await InvokeSearchAsync(provider, "hello"); + + 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)); + using var open = KnowledgeScopeScope.Open( + new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }); + + var results = await InvokeSearchAsync(provider, "the screen says e33"); + + Assert.Empty(results); + } + + [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)); + + var results = await InvokeSearchAsync(provider, "f63 error e03"); + + Assert.Empty(results); + } + + [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)); + using var open = KnowledgeScopeScope.Open( + new KnowledgeScope { Facets = new Dictionary { ["model"] = "ct900" } }); + + var results = await InvokeSearchAsync(provider, "f63 error e03"); + + Assert.All(results, r => Assert.Equal("agentcore:notice", r.SourceName)); + } + + [Fact] + public async Task Search_ToolModeThatThrows_StillSaysUnreachable() + { + var provider = Provider( + new ThrowingKnowledgePort(new InvalidOperationException("boom")), Resolved(KnowledgeMode.Tool)); + + var results = await InvokeSearchAsync(provider, "f63"); + + Assert.Contains(results, r => r.Text.Contains("unreachable", StringComparison.Ordinal)); + } + /// 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. @@ -612,6 +686,45 @@ private static AIContextProvider Provider(IKnowledgeRetrievalPort port, Resolved => KnowledgeProviderFactory.Create( port, knowledge, "agent-under-test", new SourceLocatorCitationFormatter(), loggers: null); + /// + /// Calls the factory's own search delegate directly, rather than through + /// . The guard under test reads + /// itself, so it behaves identically whether the framework + /// would have called the delegate before the model (prefetch) or handed it to the model as a + /// tool -- TextSearchProvider only decides which of those two happens, and in tool mode + /// never calls the delegate on its own. + /// + /// + /// Reaches into Microsoft.Agents.AI.TextSearchProvider's private + /// Func<string, CancellationToken, Task<IEnumerable<TextSearchResult>>> _searchAsync + /// field by reflection, verified against Microsoft.Agents.AI 1.17.0. That field is the only + /// way to reach the delegate uniformly across both SearchTime modes: in + /// OnDemandFunctionCalling the framework never calls it before the model does, and its own + /// SearchAsync(string, CancellationToken) wraps it into a formatted string rather than the + /// raw list these tests need to inspect. + /// + /// The provider built. + /// The search text. + /// What the delegate returned. + /// + /// TextSearchProvider no longer declares the private _searchAsync field this helper + /// depends on -- a newer Microsoft.Agents.AI changed its internals and this helper needs + /// updating for the new shape, rather than the caller seeing a bare . + /// + private static async Task> InvokeSearchAsync( + AIContextProvider provider, string query) + { + var field = typeof(TextSearchProvider).GetField("_searchAsync", BindingFlags.NonPublic | BindingFlags.Instance) + ?? throw new InvalidOperationException( + "TextSearchProvider no longer has a private field named '_searchAsync'. " + + "Microsoft.Agents.AI changed its internals; update InvokeSearchAsync for the new shape."); + + var searchAsync = (Func>>) + field.GetValue(provider)!; + + return (await searchAsync(query, TestContext.Current.CancellationToken).ConfigureAwait(false)).ToList(); + } + /// Every message text of a returned context, in one string. private static string Merged(AIContext context) => string.Join('\n', Texts(context)); diff --git a/tests/AgentCore.Application.Tests/Knowledge/StateKnowledgeScopeTests.cs b/tests/AgentCore.Application.Tests/Knowledge/StateKnowledgeScopeTests.cs new file mode 100644 index 00000000..ef9725ea --- /dev/null +++ b/tests/AgentCore.Application.Tests/Knowledge/StateKnowledgeScopeTests.cs @@ -0,0 +1,115 @@ +using System.Text.Json.Nodes; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Knowledge; +using AgentCore.Application.State; +using AgentCore.Domain.Knowledge; +using Xunit; + +namespace AgentCore.Application.Tests.Knowledge; + +public sealed class StateKnowledgeScopeTests +{ + private static readonly KnowledgeScopeConfiguration Configured = new() + { + Template = "facets.{key}", + Wildcard = new() { Value = "*", Facets = ["brand", "applies_to"] }, + FromState = ["brand", "applies_to"], + }; + + private static StateDocument Document() + { + StateSlotConfiguration Slot(params string[] members) => new() + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + EnumValues = [.. members.Select(m => (JsonNode)JsonValue.Create(m)!)], + }; + + return new StateDocument(new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Name = "doc", + State = new Dictionary(StringComparer.Ordinal) + { + ["brand"] = Slot("sole", "spirit"), + ["applies_to"] = Slot("f63", "f80"), + }, + }); + } + + [Fact] + public void Compose_NothingKnown_IsAllWildcard() + { + var scope = StateKnowledgeScope.Compose(Document(), Configured, ambient: null); + + 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")); + + var scope = StateKnowledgeScope.Compose(state, Configured, ambient: null); + + 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 ambient = new() + { + Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "spirit" }, + }; + + var scope = StateKnowledgeScope.Compose(state, Configured, ambient); + + Assert.Equal("spirit", scope!.Facets["brand"]); + } + + [Fact] + public void Compose_NoFromState_ReturnsTheAmbientInstance() + { + KnowledgeScope ambient = new() + { + Facets = new Dictionary(StringComparer.Ordinal) { ["brand"] = "sole" }, + }; + + var scope = StateKnowledgeScope.Compose( + Document(), Configured with { FromState = [] }, ambient); + + Assert.Same(ambient, scope); + } + + [Fact] + public void Compose_NoWildcard_ReturnsTheAmbientInstance() + { + var scope = StateKnowledgeScope.Compose( + Document(), Configured with { Wildcard = null }, ambient: null); + + Assert.Null(scope); + } + + [Fact] + public void Compose_MarksEachFacetWithItsOrigin() + { + var 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)!; + + 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/Runtime/CallSessionTests.cs b/tests/AgentCore.Application.Tests/Runtime/CallSessionTests.cs index 2c35c8f9..5245ffe4 100644 --- a/tests/AgentCore.Application.Tests/Runtime/CallSessionTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/CallSessionTests.cs @@ -420,6 +420,29 @@ public async Task TheExtractor_ReadsTheFinishedTurn() Assert.DoesNotContain(request, message => Contains(message, UnfilledSlotReminder.OpenTag)); } + [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 AFailedExtraction_DoesNotDropTheTurn() { diff --git a/tests/AgentCore.Application.Tests/Runtime/KnowledgeScopeThroughCallSessionTests.cs b/tests/AgentCore.Application.Tests/Runtime/KnowledgeScopeThroughCallSessionTests.cs index dfaa94f8..690d78c9 100644 --- a/tests/AgentCore.Application.Tests/Runtime/KnowledgeScopeThroughCallSessionTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/KnowledgeScopeThroughCallSessionTests.cs @@ -1,3 +1,6 @@ +using System.Runtime.CompilerServices; +using System.Text.Json.Nodes; +using AgentCore.Application.Calls; using AgentCore.Application.Configuration.Compilation; using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Validation; @@ -5,6 +8,7 @@ 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; @@ -44,6 +48,50 @@ public sealed class KnowledgeScopeThroughCallSessionTests - { 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 = + """ + apiVersion: agentcore/v1 + name: knowledge-scope-through-callsession-scoped + state: + brand: { type: string, writer: extractor, enum: [sole, other] } + applies_to: { type: string, writer: extractor, enum: [f63, other] } + extractor: + model: { ref: fill } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + wildcard: + value: "*" + facets: [brand, applies_to] + fromState: [brand, applies_to] + agents: + items: + - id: only + instructions: "answer the caller" + knowledge: { mode: prefetch, scoped: true } + policy: + initial: greeting + stages: + - { id: greeting, agent: only } + """; + + private StubKnowledgePort _port = null!; + [Fact] public async Task RunTurnAsync_UnderAHostScope_TheStoreStillSeesThatScope() { @@ -119,15 +167,174 @@ public async Task RunTurnAsync_AfterTheTurn_PutsBackWhatTheHostHadOpen() Assert.Null(KnowledgeScopeScope.Current); } - private static CallSessionFactory Build(SequencedChatClient reply, StubKnowledgePort port) + [Fact] + public async Task Scope_ResumedCall_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_ResumedCall_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_IsTheSameOnFirstAndLastUpdate() + { + // _port.ScopeAtTheStore is written exactly once, by the single prefetch search "mode: + // prefetch" runs before the model call — reading it after every streamed update proves + // nothing about later re-entries, because the field never changes again no matter what a + // later EnterAmbients call composes. ScopeSamplingChatClient instead reads the ambient from + // inside its own fragment loop, which ScopedEnumerator re-enters through EnterAmbients on + // every streaming step, so each sample reflects exactly what that step's own scope held. + using ScopeSamplingChatClient reply = new("hello ", "there."); + var session = FreshSession(reply); + + await foreach (var _ in session.RunTurnStreamingAsync("hello", TestContext.Current.CancellationToken)) + { + } + + Assert.True(reply.Samples.Count >= 2, "the fake reply must yield at least two fragments, or this never observes a re-entry."); + Assert.All(reply.Samples, sample => Assert.Same(reply.Samples[0], sample)); + Assert.Same(reply.Samples[0], _port.ScopeAtTheStore); + } + + /// + /// A model that streams fragments one at a time and records the knowledge ambient immediately + /// before each is yielded. Unlike , which only proves the seam + /// drops empty updates, this proves what the ambient holds from inside a fragment's own scope — + /// which a field the store's stub sets once cannot, because it never changes again regardless of + /// how many more times EnterAmbients runs afterward. + /// + private sealed class ScopeSamplingChatClient : IChatClient + { + private readonly string[] _fragments; + + public ScopeSamplingChatClient(params string[] fragments) => _fragments = fragments; + + /// Gets the ambient scope read immediately before each fragment was yielded, in order. + public List Samples { get; } = []; + + 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"); + + foreach (var fragment in _fragments) + { + Samples.Add(KnowledgeScopeScope.Current); + 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)) + { + 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() + { + } + } + + private static CallSessionFactory Build(IChatClient reply, StubKnowledgePort port, string yaml = Yaml) { var compiled = ConfigurationCompiler.Compile( - ConfigurationLoader.LoadYaml(Yaml), + ConfigurationLoader.LoadYaml(yaml), new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = port }); return new CallSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); } + private CallSession FreshSession(IChatClient reply) + { + _port = new StubKnowledgePort([Card("a")]); + + return Build(reply, _port, ScopedYaml).Create("call-fresh"); + } + + private CallSession ResumedSession(IChatClient reply, IReadOnlyDictionary stored) + { + _port = new StubKnowledgePort([Card("a")]); + + // The real restore path: a CallSessionState of the shape store 0 hands back, fed through + // CallSessionFactory.Create so Resume/Restore write the slots, rather than the test poking + // session.State directly and skipping the coercion and enum checks Restore applies. + CallSessionState state = new() + { + Stage = "greeting", + Slots = stored.ToDictionary( + pair => pair.Key, + pair => (JsonNode?)JsonValue.Create(pair.Value), + StringComparer.Ordinal), + }; + + return Build(reply, _port, ScopedYaml).Create("call-resumed", state); + } + private static KnowledgeScope Scope() => new() { Facets = new Dictionary { ["model"] = "ct900" } }; diff --git a/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs b/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs index 6c74a7ba..27b643f6 100644 --- a/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs +++ b/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs @@ -45,6 +45,49 @@ public sealed class StateDocumentTests - { id: only } """; + private static AgentCoreConfiguration WithEnumSlot() => new() + { + ApiVersion = "agentcore/v1", + Name = "doc", + State = new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = 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()); + + Assert.False(state.TryWrite("applies_to", JsonValue.Create("F63 Treadmill"))); + Assert.True(state.IsUnfilled("applies_to")); + } + + [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("f80"))); + Assert.Equal("f63", state.Read("applies_to")?.GetValue()); + } + + [Fact] + public void TryWrite_ValueInsideTheEnum_IsAccepted() + { + var state = new StateDocument(WithEnumSlot()); + + Assert.True(state.TryWrite("applies_to", JsonValue.Create("f65"))); + Assert.Equal("f65", state.Read("applies_to")?.GetValue()); + } + [Fact] public void WrittenSlots_HandsOutAFreshCopyEveryCall() { diff --git a/tests/AgentCore.Domain.Tests/Knowledge/KnowledgeScopeTests.cs b/tests/AgentCore.Domain.Tests/Knowledge/KnowledgeScopeTests.cs new file mode 100644 index 00000000..62803781 --- /dev/null +++ b/tests/AgentCore.Domain.Tests/Knowledge/KnowledgeScopeTests.cs @@ -0,0 +1,22 @@ +using AgentCore.Domain.Knowledge; +using Xunit; + +namespace AgentCore.Domain.Tests.Knowledge; + +public sealed class KnowledgeScopeTests +{ + [Fact] + public void TwoScopes_WithTheSameFacetsAndNoOrigins_AreEqual() + { + IReadOnlyDictionary facets = new Dictionary(StringComparer.Ordinal) + { + ["brand"] = "sole", + }; + + var first = new KnowledgeScope { Facets = facets }; + var second = new KnowledgeScope { Facets = facets }; + + Assert.Equal(first, second); + Assert.Equal(first.GetHashCode(), second.GetHashCode()); + } +} 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 429e5826..3ed07cf0 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/CapturingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/CapturingSearchChannel.cs @@ -29,7 +29,7 @@ public CapturingSearchChannel( } /// Gets the fused query the store built, or null when it never searched. - public FusedQuery? Query { get; private set; } + 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; } @@ -57,7 +57,7 @@ Query is null .Where(condition => condition.Field is { Match.Text.Length: > 0 }) .Select(condition => condition.Field.Key)]; - public Task> QueryAsync(FusedQuery query, CancellationToken cancellationToken) + public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) { Query = query; return Task.FromResult(_ranked); 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 88bcb966..82f8345c 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/HangingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/HangingSearchChannel.cs @@ -10,7 +10,7 @@ internal sealed class HangingSearchChannel : IQdrantSearchChannel public HangingSearchChannel(TimeSpan delay) => _delay = delay; - public async Task> QueryAsync(FusedQuery query, CancellationToken cancellationToken) + public async Task> QueryAsync(SearchQuery query, 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 0d89137a..d35619a5 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/RecordingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/RecordingSearchChannel.cs @@ -22,7 +22,7 @@ internal sealed class RecordingSearchChannel : IQdrantSearchChannel /// Gets every id set was called with, in call order. public List> RetrievedIds { get; } = []; - public Task> QueryAsync(FusedQuery query, CancellationToken cancellationToken) => + public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) => Task.FromResult(_queryResult); public Task> RetrieveAsync( diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs index d18a50b9..1e9c1f30 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs @@ -831,6 +831,30 @@ public async Task CreateSearchAsync_CustomAnalyzer_IsSelectedByName() (store as IDisposable)?.Dispose(); } + [QdrantFact] + public async Task CreateSearchAsync_DocumentDeclaresAWildcard_ReachesTheStoreOptions() + { + var entry = Entry() with + { + Scope = KbShapedCorpus.Scope with { Wildcard = new() { Value = "*", Facets = ["model"] } }, + }; + + var port = await Adapter().CreateSearchAsync( + entry, secrets: null, Embedder(), requireScope: true, TestContext.Current.CancellationToken); + + // QdrantKnowledgeStore keeps its options private, so reflection is the only way to observe + // what the adapter copied onto them. The filter those options go on to produce is covered by + // QdrantWildcardScopeTests. + var options = (QdrantKnowledgeStoreOptions)typeof(QdrantKnowledgeStore) + .GetField("_options", BindingFlags.NonPublic | BindingFlags.Instance)! + .GetValue(port)!; + + Assert.Equal("*", options.ScopeWildcard); + Assert.Equal(["model"], options.ScopeWildcardFacets); + + (port as IDisposable)?.Dispose(); + } + [Fact] public async Task CreateSearchAsync_UnknownMapper_FailsTheLoadPointingAtMapper() { diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs index 842ed05f..ea7d5216 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs @@ -120,9 +120,9 @@ 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 }; - // 0.25 is exact in float32. At 0.1 the value round-trips to 0.10000000149011612 and the - // floor's `>=` cannot be told from `>`. - Assert.Equal(0.25, options.ScoreFloor); + // 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); @@ -172,19 +172,19 @@ public async Task SearchAsync_LimitAboveTheDefaultPrefetchDepth_ReturnsThatMany( [QdrantFact] public async Task SearchAsync_ScoreFloor_KeepsExactlyTheCardsAtOrAboveIt() { - // The floor must be exact in float32, or `>=` cannot be told from `>`. + // 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, TestContext.Current.CancellationToken); - var floored = await Store(floor: 0.25, limit: 20, scoped: false).SearchAsync( - KbShapedCorpus.PlainQuery, TestContext.Current.CancellationToken); + Assert.True(all.Count >= 3); + var floor = (all[1].Score!.Value + all[2].Score!.Value) / 2; - var atOrAbove = all.Count(card => card.Score >= 0.25); + var floored = await Store(floor: floor, limit: 20, scoped: false).SearchAsync( + KbShapedCorpus.PlainQuery, TestContext.Current.CancellationToken); - // The boundary is only testable while some card scores exactly 0.25 and some card scores - // less. Without both, `>=` and `>` agree and the comparison below proves nothing. - Assert.Contains(all, card => card.Score == 0.25); - Assert.Contains(all, card => card.Score < 0.25); - Assert.Equal(atOrAbove, floored.Count(card => !card.ViaLink)); + Assert.Equal(2, floored.Count(card => !card.ViaLink)); + Assert.All(floored.Where(card => !card.ViaLink), card => Assert.True(card.Score > floor)); } [QdrantFact] diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantSearchChannelTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantSearchChannelTests.cs index c25cb98c..5441cd09 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantSearchChannelTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantSearchChannelTests.cs @@ -32,7 +32,7 @@ public async Task QueryAsync_ReturnsPointsInFusedOrder() }; var points = await channel.QueryAsync( - new FusedQuery(collection, [prefetch], new Query { Fusion = Fusion.Rrf }, 5), + new SearchQuery(collection, [prefetch], new Query { Fusion = Fusion.Rrf }, 5), TestContext.Current.CancellationToken); Assert.Equal(5, points.Count); @@ -79,6 +79,6 @@ public async Task QueryAsync_CancelledToken_Throws() await cancelled.CancelAsync(); await Assert.ThrowsAnyAsync(async () => await channel.QueryAsync( - new FusedQuery("anything", [], new Query { Fusion = Fusion.Rrf }, 1), cancelled.Token)); + new SearchQuery("anything", [], new Query { Fusion = Fusion.Rrf }, 1), cancelled.Token)); } } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantWildcardScopeTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantWildcardScopeTests.cs new file mode 100644 index 00000000..0349d3f1 --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantWildcardScopeTests.cs @@ -0,0 +1,158 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Runtime; +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; +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 +{ + [Fact] + public async Task Search_NoWildcardConfigured_EmitsTheKeywordCase() + { + var channel = new CapturingSearchChannel([]); + var store = StoreOver(channel, wildcard: null, wildcardFacets: []); + + using (KnowledgeScopeScope.Open(Scope(("brand", "sole")))) + { + await store.SearchAsync("belt", 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"]); + + using (KnowledgeScopeScope.Open(Scope(("brand", "sole")))) + { + await store.SearchAsync("belt", 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"]); + + using (KnowledgeScopeScope.Open(Scope(("brand", "sole"), ("customer_id", "c-91")))) + { + await store.SearchAsync("belt", 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_ValueEqualsTheWildcard_EmitsOneKeyword() + { + var channel = new CapturingSearchChannel([]); + var store = StoreOver(channel, wildcard: "*", wildcardFacets: ["brand"]); + + using (KnowledgeScopeScope.Open(Scope(("brand", "*")))) + { + await store.SearchAsync("belt", TestContext.Current.CancellationToken); + } + + 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_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); + + using (KnowledgeScopeScope.Open(Scope(("brand", "sole")))) + { + var cards = await store.SearchAsync("belt", TestContext.Current.CancellationToken); + Assert.Contains(cards, card => card.ViaLink); + } + } + + [Fact] + public async Task Search_LinkedCardOutsideTheScope_IsDropped() + { + var store = StoreOver( + ChannelWithLink(linkedFacet: "spirit"), wildcard: "*", wildcardFacets: ["brand"], withLinks: true); + + using (KnowledgeScopeScope.Open(Scope(("brand", "sole")))) + { + var cards = await store.SearchAsync("belt", TestContext.Current.CancellationToken); + Assert.DoesNotContain(cards, card => card.ViaLink); + } + } + + /// A ranked point linking to one fetched point tagged on brand. + private static CapturingSearchChannel ChannelWithLink(string linkedFacet) + { + var linkedId = Guid.NewGuid(); + + 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 + { + 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; + + return new CapturingSearchChannel([ranked], [fetched]); + } + + private static QdrantKnowledgeStore StoreOver( + CapturingSearchChannel channel, + string? wildcard, + IReadOnlyList wildcardFacets, + bool withLinks = false) => 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 new file mode 100644 index 00000000..d9d783fc --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/ScoreFloorOnPrefetchTests.cs @@ -0,0 +1,124 @@ +using AgentCore.Application.Configuration.Schema; +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 +{ + /// 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() + { + var channel = new CapturingSearchChannel(Points(RankScores)); + + await Store(channel, floor: 0.35).SearchAsync("belt", 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); + } + + [Fact] + public async Task SearchAsync_WithZeroFloor_EmitsNoScoreThreshold() + { + var channel = new CapturingSearchChannel(Points(RankScores)); + + await Store(channel, floor: 0.0).SearchAsync("belt", 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"); + } + + [Fact] + public async Task SearchAsync_DoesNotCutTheReturnedPointsByScore() + { + var channel = new CapturingSearchChannel(Points(RankScores)); + + var cards = await Store(channel, floor: 0.35).SearchAsync("belt", 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); + } + + [Fact] + public async Task SearchAsync_WithOneLeg_AsksForTheNearestVectorRatherThanAFusion() + { + var channel = new CapturingSearchChannel(Points(RankScores)); + + await Store(channel, floor: 0.35).SearchAsync("belt", 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); + } + + [Fact] + public async Task SearchAsync_WithOneLegOverAnAnonymousVector_NamesNoVectorAnywhere() + { + var channel = new CapturingSearchChannel(Points(RankScores)); + + await Store(channel, floor: 0.35).SearchAsync("belt", TestContext.Current.CancellationToken); + + 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)); + + await Store(channel, floor: 0.35, vector: "dense").SearchAsync("belt", TestContext.Current.CancellationToken); + + 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)); + + await Store(channel, floor: 0.35, vector: string.Empty).SearchAsync("belt", TestContext.Current.CancellationToken); + + 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) => + { + 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 + { + 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/TestScopes.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/TestScopes.cs new file mode 100644 index 00000000..a5cf204c --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/TestScopes.cs @@ -0,0 +1,12 @@ +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 +{ + internal static KnowledgeScope Scope(params (string Key, string Value)[] facets) => new() + { + Facets = facets.ToDictionary(facet => facet.Key, facet => facet.Value, StringComparer.Ordinal), + }; +} diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/WildcardScopeIntegrationTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/WildcardScopeIntegrationTests.cs new file mode 100644 index 00000000..cea8c70b --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/WildcardScopeIntegrationTests.cs @@ -0,0 +1,188 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Runtime; +using AgentCore.Domain.Knowledge; +using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; +using AgentCore.Infrastructure.Tests.Fakes; +using Qdrant.Client; +using Qdrant.Client.Grpc; +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 +{ + /// 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}"; + + /// Gets the client the tests query through. + public QdrantClient Client { get; private set; } = null!; + + public async ValueTask InitializeAsync() + { + if (!QdrantServer.IsConfigured) + { + return; + } + + Client = QdrantServer.CreateClient(); + + 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[] + { + 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); + } + + public async ValueTask DisposeAsync() + { + 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 + { + 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 + { + Fields = + { + ["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; + } +} + +/// +/// 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; + + public WildcardScopeIntegrationTests(WildcardScopeCorpusFixture corpus) => _corpus = corpus; + + [QdrantFact] + public async Task Search_NothingKnown_ReturnsOnlyTheCompanyWideCard() + { + using (KnowledgeScopeScope.Open(Scope(("brand", "*"), ("applies_to", "*")))) + { + var cards = await Store.SearchAsync("belt", TestContext.Current.CancellationToken); + Assert.Equal(["policy"], cards.Select(c => c.CardId).Order(StringComparer.Ordinal)); + } + } + + [QdrantFact] + public async Task Search_BrandOnly_AdmitsBrandWideAndRefusesTheMachineCard() + { + using (KnowledgeScopeScope.Open(Scope(("brand", "sole"), ("applies_to", "*")))) + { + var cards = await Store.SearchAsync("belt", 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); + } + } + + [QdrantFact] + public async Task Search_BrandAndMachine_AdmitsAllThree() + { + using (KnowledgeScopeScope.Open(Scope(("brand", "sole"), ("applies_to", "f63")))) + { + var cards = await Store.SearchAsync("belt", 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); + } + } + + 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, + }); +} From fd4f7f7a36f38a95cd78514bfc416962534d9262 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Fri, 4 Sep 2026 14:20:14 -0600 Subject: [PATCH 2/4] - Introduced FacetVocabularyTests to validate reading distinct values and handling of keyword indexes in Qdrant. - Added negative limit check in QdrantKnowledgeStoreTests to ensure proper exception handling. - Implemented FacetAsync method in various fake search channels to support testing. - Created TextSearchProviderInternals to access private search delegate for testing purposes. - Ensured proper setup and teardown of test data in FacetVocabularyCorpusFixture. --- AgentCore.sln | 15 + .../AgentCore.Application.csproj | 1 + .../Calls/CallClarificationState.cs | 19 + .../Calls/CallSessionState.cs | 10 + .../Compilation/AgentKnowledge.cs | 9 +- .../Compilation/ConfigurationCompiler.cs | 44 +- .../Compilation/ResolvedClarification.cs | 102 ++ .../Parsing/ConfigurationCheck.cs | 10 +- .../Configuration/Parsing/ScopeTemplate.cs | 45 + .../Schema/ProvidersConfiguration.cs | 45 + .../Schema/StateSlotConfiguration.cs | 44 + .../Schema/agentcore-v1.schema.json | 64 + .../Validation/ConfigurationValidator.cs | 335 ++++- src/AgentCore.Application/Diagnostics/Log.cs | 27 + .../CompositeKnowledgeStoreFactory.cs | 5 +- .../Knowledge/KnowledgeCancellation.cs | 34 + .../Knowledge/KnowledgeNotices.cs | 35 + .../Knowledge/KnowledgeProbe.cs | 357 +++++ .../Knowledge/KnowledgeProviderFactory.cs | 96 +- .../Knowledge/KnowledgeSearchRecord.cs | 41 + .../Ports/IFacetVocabularyPort.cs | 17 + .../PublicAPI.Unshipped.txt | 557 +++++--- .../AuditingFunctionInvokingChatClient.cs | 10 +- .../Runtime/CallSession.cs | 170 ++- .../Runtime/CallSessionFactory.cs | 39 +- .../Runtime/ClarificationProvider.cs | 134 ++ .../Runtime/ClarificationText.cs | 110 ++ .../Runtime/Clarifications.cs | 435 ++++++ .../Runtime/OuterToolCall.cs | 13 +- .../Runtime/TurnAmbients.cs | 9 +- .../Runtime/TurnContextScope.cs | 9 + .../State/ExactStateValueLinker.cs | 274 ++++ .../State/IStateValueLinker.cs | 23 + src/AgentCore.Application/State/LinkResult.cs | 55 + .../State/StateDocument.cs | 43 +- .../State/StateExtractor.cs | 164 ++- .../State/StateValueLinkers.cs | 51 + .../State/VocabularyCache.cs | 112 ++ .../State/VocabularyException.cs | 97 ++ .../State/VocabularyFold.cs | 103 ++ .../State/VocabularyView.cs | 19 + .../DependencyInjection/AgentCoreBoot.cs | 95 +- .../DependencyInjection/AgentCoreOptions.cs | 14 + .../Startup/CallSessionStartup.cs | 8 +- .../Startup/ConfigurationStartup.cs | 21 +- .../Startup/KnowledgeStartup.cs | 217 +++ .../PublicAPI.Unshipped.txt | 1 + .../Sessions/VocabularyRefreshService.cs | 102 ++ src/AgentCore.Domain/Knowledge/PayloadPath.cs | 39 + src/AgentCore.Domain/PublicAPI.Unshipped.txt | 2 + .../VectorData/Qdrant/FieldsPointMapper.cs | 27 +- .../VectorData/Qdrant/IQdrantSearchChannel.cs | 9 + .../VectorData/Qdrant/QdrantKnowledgeStore.cs | 29 +- .../VectorData/Qdrant/QdrantSearchChannel.cs | 13 + .../ClarificationWiringBindingTests.cs | 222 +++ .../Configuration/AgentKnowledgeTests.cs | 14 + .../Configuration/ConfigurationBinderTests.cs | 176 +++ .../Validation/ConfigurationValidatorTests.cs | 564 +++++++- .../Knowledge/Fakes/StubKnowledgePort.cs | 5 + .../Knowledge/KnowledgeProbeTests.cs | 1221 +++++++++++++++++ .../KnowledgeProviderFactoryTests.cs | 28 +- ...ngFunctionInvokingChatClientRenderTests.cs | 2 +- ...ingFunctionInvokingChatClientStripTests.cs | 158 +++ .../Runtime/CallSessionClarificationTests.cs | 363 +++++ .../Runtime/CallSessionProbeTests.cs | 282 ++++ .../Runtime/ClarificationProviderTests.cs | 540 ++++++++ .../Runtime/ClarificationTextTests.cs | 155 +++ .../Runtime/ClarificationsTests.cs | 394 ++++++ .../Runtime/TurnAmbientsTestScope.cs | 19 +- .../State/ExactStateValueLinkerTests.cs | 358 +++++ .../State/StateDocumentTests.cs | 43 + .../State/StateExtractorLinkerTests.cs | 299 ++++ .../State/VocabularyCacheTests.cs | 288 ++++ .../State/VocabularyFoldTests.cs | 112 ++ .../.editorconfig | 5 + ...AgentCore.Application.Unicode.Tests.csproj | 28 + .../State/VocabularyFoldCompositionTests.cs | 39 + .../VocabularyStartupTests.cs | 743 ++++++++++ .../Sessions/VocabularyRefreshServiceTests.cs | 136 ++ .../Qdrant/AmbiguityIntegrationTests.cs | 878 ++++++++++++ .../VectorData/Qdrant/FacetVocabularyTests.cs | 173 +++ .../Qdrant/Fakes/CapturingSearchChannel.cs | 4 + .../Qdrant/Fakes/HangingSearchChannel.cs | 7 + .../Qdrant/Fakes/RecordingSearchChannel.cs | 4 + .../Qdrant/QdrantKnowledgeStoreTests.cs | 19 + .../TextSearchProviderInternals.cs | 58 + 86 files changed, 11256 insertions(+), 440 deletions(-) create mode 100644 src/AgentCore.Application/Calls/CallClarificationState.cs create mode 100644 src/AgentCore.Application/Configuration/Compilation/ResolvedClarification.cs create mode 100644 src/AgentCore.Application/Configuration/Parsing/ScopeTemplate.cs create mode 100644 src/AgentCore.Application/Knowledge/KnowledgeCancellation.cs create mode 100644 src/AgentCore.Application/Knowledge/KnowledgeNotices.cs create mode 100644 src/AgentCore.Application/Knowledge/KnowledgeProbe.cs create mode 100644 src/AgentCore.Application/Knowledge/KnowledgeSearchRecord.cs create mode 100644 src/AgentCore.Application/Ports/IFacetVocabularyPort.cs create mode 100644 src/AgentCore.Application/Runtime/ClarificationProvider.cs create mode 100644 src/AgentCore.Application/Runtime/ClarificationText.cs create mode 100644 src/AgentCore.Application/Runtime/Clarifications.cs create mode 100644 src/AgentCore.Application/State/ExactStateValueLinker.cs create mode 100644 src/AgentCore.Application/State/IStateValueLinker.cs create mode 100644 src/AgentCore.Application/State/LinkResult.cs create mode 100644 src/AgentCore.Application/State/StateValueLinkers.cs create mode 100644 src/AgentCore.Application/State/VocabularyCache.cs create mode 100644 src/AgentCore.Application/State/VocabularyException.cs create mode 100644 src/AgentCore.Application/State/VocabularyFold.cs create mode 100644 src/AgentCore.Application/State/VocabularyView.cs create mode 100644 src/AgentCore.AspNetCore/Sessions/VocabularyRefreshService.cs create mode 100644 src/AgentCore.Domain/Knowledge/PayloadPath.cs create mode 100644 tests/AgentCore.Application.Tests/Compilation/ClarificationWiringBindingTests.cs create mode 100644 tests/AgentCore.Application.Tests/Knowledge/KnowledgeProbeTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientStripTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/CallSessionClarificationTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/CallSessionProbeTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/ClarificationProviderTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/ClarificationTextTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/ClarificationsTests.cs create mode 100644 tests/AgentCore.Application.Tests/State/ExactStateValueLinkerTests.cs create mode 100644 tests/AgentCore.Application.Tests/State/StateExtractorLinkerTests.cs create mode 100644 tests/AgentCore.Application.Tests/State/VocabularyCacheTests.cs create mode 100644 tests/AgentCore.Application.Tests/State/VocabularyFoldTests.cs create mode 100644 tests/AgentCore.Application.Unicode.Tests/.editorconfig create mode 100644 tests/AgentCore.Application.Unicode.Tests/AgentCore.Application.Unicode.Tests.csproj create mode 100644 tests/AgentCore.Application.Unicode.Tests/State/VocabularyFoldCompositionTests.cs create mode 100644 tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs create mode 100644 tests/AgentCore.AspNetCore.Tests/Sessions/VocabularyRefreshServiceTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/AmbiguityIntegrationTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetVocabularyTests.cs create mode 100644 tests/AgentCore.TestSupport/TextSearchProviderInternals.cs diff --git a/AgentCore.sln b/AgentCore.sln index 4d2e451e..9beaf91c 100644 --- a/AgentCore.sln +++ b/AgentCore.sln @@ -33,6 +33,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AgentCore.TestSupport", "te EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AgentCore.AspNetCore", "src\AgentCore.AspNetCore\AgentCore.AspNetCore.csproj", "{DB5D8634-2691-4048-A6F7-FFA9F6016FE2}" EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AgentCore.Application.Unicode.Tests", "tests\AgentCore.Application.Unicode.Tests\AgentCore.Application.Unicode.Tests.csproj", "{5586509D-101A-4F39-8161-15ED573E7EC9}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -187,6 +189,18 @@ Global {DB5D8634-2691-4048-A6F7-FFA9F6016FE2}.Release|x64.Build.0 = Release|Any CPU {DB5D8634-2691-4048-A6F7-FFA9F6016FE2}.Release|x86.ActiveCfg = Release|Any CPU {DB5D8634-2691-4048-A6F7-FFA9F6016FE2}.Release|x86.Build.0 = Release|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|Any CPU.Build.0 = Debug|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|x64.ActiveCfg = Debug|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|x64.Build.0 = Debug|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|x86.ActiveCfg = Debug|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|x86.Build.0 = Debug|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Release|Any CPU.ActiveCfg = Release|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Release|Any CPU.Build.0 = Release|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Release|x64.ActiveCfg = Release|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Release|x64.Build.0 = Release|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Release|x86.ActiveCfg = Release|Any CPU + {5586509D-101A-4F39-8161-15ED573E7EC9}.Release|x86.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -204,5 +218,6 @@ Global {DE0D9F78-60D2-4A95-B71C-E01480048CA0} = {0AB3BF05-4346-4AA6-1389-037BE0695223} {E70C6362-5778-4498-9BA9-7FED110762AE} = {0AB3BF05-4346-4AA6-1389-037BE0695223} {DB5D8634-2691-4048-A6F7-FFA9F6016FE2} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B} + {5586509D-101A-4F39-8161-15ED573E7EC9} = {0AB3BF05-4346-4AA6-1389-037BE0695223} EndGlobalSection EndGlobal diff --git a/src/AgentCore.Application/AgentCore.Application.csproj b/src/AgentCore.Application/AgentCore.Application.csproj index 0b947998..931cf630 100644 --- a/src/AgentCore.Application/AgentCore.Application.csproj +++ b/src/AgentCore.Application/AgentCore.Application.csproj @@ -38,6 +38,7 @@ + diff --git a/src/AgentCore.Application/Calls/CallClarificationState.cs b/src/AgentCore.Application/Calls/CallClarificationState.cs new file mode 100644 index 00000000..c8191249 --- /dev/null +++ b/src/AgentCore.Application/Calls/CallClarificationState.cs @@ -0,0 +1,19 @@ +namespace AgentCore.Application.Calls; + +/// What one slot's ambiguity channels have already spent of their ask budget (§7, §8). +/// +/// Carried on so a caller who drops and reconnects mid-call 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 CallClarificationState +{ + /// Gets how many times the knowledge probe has offered this slot (§8, K22). + public int ProbeAsks { get; init; } + + /// Gets how many times the clarification instruction has named this slot (§7). + public int NamedAsks { get; init; } + + /// Gets whether §7 step 3's one counter reset has already been spent. + public bool ResetSpent { get; init; } +} diff --git a/src/AgentCore.Application/Calls/CallSessionState.cs b/src/AgentCore.Application/Calls/CallSessionState.cs index f0f0172d..d557ecb8 100644 --- a/src/AgentCore.Application/Calls/CallSessionState.cs +++ b/src/AgentCore.Application/Calls/CallSessionState.cs @@ -10,6 +10,10 @@ public sealed record CallSessionState private static readonly IReadOnlyDictionary NoSlots = ReadOnlyDictionary.Empty; + /// The slots of a call whose ambiguity channels asked about none. + private static readonly IReadOnlyDictionary NoClarifications = + ReadOnlyDictionary.Empty; + /// The shape this version of the library writes. public const int CurrentVersion = 1; @@ -30,4 +34,10 @@ public sealed record CallSessionState /// 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 ambiguity channels have spent of their ask budget, by slot name. A slot + /// nothing has asked about is absent. + /// + public IReadOnlyDictionary Clarifications { get; init; } = NoClarifications; } diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentKnowledge.cs b/src/AgentCore.Application/Configuration/Compilation/AgentKnowledge.cs index 03e062bc..433fd672 100644 --- a/src/AgentCore.Application/Configuration/Compilation/AgentKnowledge.cs +++ b/src/AgentCore.Application/Configuration/Compilation/AgentKnowledge.cs @@ -10,7 +10,14 @@ namespace AgentCore.Application.Configuration.Compilation; /// 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); +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 diff --git a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs index 711574d1..1fb0665d 100644 --- a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs @@ -49,6 +49,12 @@ namespace AgentCore.Application.Configuration.Compilation; /// public static class ConfigurationCompiler { + /// + /// 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(); + /// Picks the row of the compile table one document selects. /// The loaded document. /// The row. @@ -194,6 +200,15 @@ private static Dictionary BuildAgents( return agents; } + var clarification = ResolvedClarification.From(configuration); + + // Nothing on this provider is per agent: its three fields are the document's own wiring, and + // every other value it reads comes off the turn's ambients. The framework only ever calls + // into it, passing the agent and the session as arguments, so one instance serves them all. + var clarificationProvider = clarification.Ambiguity is { } documentAmbiguity + ? new ClarificationProvider(documentAmbiguity, clarification.FromState, clarification.SlotDescriptions) + : null; + Dictionary tools = new(StringComparer.Ordinal); foreach (var tool in configuration.Tools) { @@ -262,7 +277,8 @@ private static Dictionary BuildAgents( Tools = BuildTools(item, tools, context, pointer, Resolve), }, ChatHistoryProvider = history, - AIContextProviders = BuildContextProviders(section.Defaults, item, context, pointer), + AIContextProviders = BuildContextProviders( + section.Defaults, item, context, pointer, clarification, clarificationProvider), }); path.RemoveAt(path.Count - 1); @@ -275,15 +291,29 @@ private static Dictionary BuildAgents( } } - /// Builds the context providers of one agent. + /// + /// Builds the context providers of one agent. and + /// are the document's ambiguity wiring (§7), the same + /// for every agent — built once by the caller rather than re-derived per agent. + /// private static List BuildContextProviders( AgentDefaults? defaults, AgentConfiguration item, AgentCompilationContext context, - string pointer) + string pointer, + ResolvedClarification clarification, + ClarificationProvider? clarificationProvider) { List providers = [new TurnContextProvider()]; + // Bound ahead of the knowledge early-return below: channel 1 asks about a scope's fromState + // slots regardless of whether THIS agent composes its own knowledge: block, because the + // clarification is document-level state, not a per-agent search setting. + if (clarificationProvider is not null) + { + providers.Add(clarificationProvider); + } + if (item.Skills.Count > 0) { if (context.Skills is not { } catalog) @@ -298,7 +328,7 @@ private static List BuildContextProviders( providers.Add(SkillsProviderFactory.Create(catalog, item.Skills, context.Loggers)); } - if (AgentKnowledge.Compose(defaults, item) is not { } knowledge) + if (AgentKnowledge.Compose(defaults, item) is not { } composed) { return providers; } @@ -313,11 +343,15 @@ private static List BuildContextProviders( + $"{nameof(IKnowledgeRetrievalPort)}, or remove the knowledge: block."); } + // The same document-level wiring channel 1 reads above, carried onto this agent's own + // resolved knowledge so the search side does not have to re-derive it. + var knowledge = composed with { Clarification = clarification }; + providers.Add(KnowledgeProviderFactory.Create( port, knowledge, item.Id, - context.Citations ?? new SourceLocatorCitationFormatter(), + context.Citations ?? DefaultCitations, context.Loggers)); return providers; diff --git a/src/AgentCore.Application/Configuration/Compilation/ResolvedClarification.cs b/src/AgentCore.Application/Configuration/Compilation/ResolvedClarification.cs new file mode 100644 index 00000000..62993bf9 --- /dev/null +++ b/src/AgentCore.Application/Configuration/Compilation/ResolvedClarification.cs @@ -0,0 +1,102 @@ +using System.Collections.ObjectModel; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; + +namespace AgentCore.Application.Configuration.Compilation; + +/// +/// The document-level ambiguity wiring §7 needs, 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, and both channels — the clarification provider and the agent's +/// own search — read the one instance. +/// +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 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. + /// + /// + /// 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; + + /// + /// 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 the facet keys widens, or empty when + /// providers.knowledge.scope.wildcard is absent. + /// + public IReadOnlyList WildcardFacets { 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; } + + /// 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); + + var knowledge = configuration.Providers?.Knowledge; + if (knowledge is null) + { + return None; + } + + var fromState = knowledge.Scope.FromState; + + Dictionary descriptions = new(StringComparer.Ordinal); + foreach (var slot in fromState) + { + descriptions[slot] = configuration.State.TryGetValue(slot, out var 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/Parsing/ConfigurationCheck.cs b/src/AgentCore.Application/Configuration/Parsing/ConfigurationCheck.cs index 9a057a66..8d269b71 100644 --- a/src/AgentCore.Application/Configuration/Parsing/ConfigurationCheck.cs +++ b/src/AgentCore.Application/Configuration/Parsing/ConfigurationCheck.cs @@ -1,7 +1,8 @@ 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. +/// 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 { @@ -31,4 +32,11 @@ public enum ConfigurationCheck /// 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, } diff --git a/src/AgentCore.Application/Configuration/Parsing/ScopeTemplate.cs b/src/AgentCore.Application/Configuration/Parsing/ScopeTemplate.cs new file mode 100644 index 00000000..25ac9ab9 --- /dev/null +++ b/src/AgentCore.Application/Configuration/Parsing/ScopeTemplate.cs @@ -0,0 +1,45 @@ +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 +{ + /// 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) + { + ArgumentNullException.ThrowIfNull(key); + + return Raw.Replace(KeyPlaceholder, key, StringComparison.Ordinal); + } + + /// + public override string ToString() => Raw; +} diff --git a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs index aee62aff..1be4229a 100644 --- a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs @@ -239,6 +239,13 @@ public sealed record KnowledgeProviderConfiguration /// 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; } @@ -266,6 +273,44 @@ public sealed record KnowledgeProviderConfiguration public double ScoreFloor { get; init; } = DefaultScoreFloor; } +/// +/// 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-and-vocabulary +/// 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 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; + + /// 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 each of a slot's two ask counters. 0 means never ask: the vocabulary + /// and the gate still work. + /// + 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 how much longer than the probe, in seconds, a concurrent loser waits for the winner's + /// payload. + /// + public int ProbeWaitMarginSeconds { get; init; } = DefaultProbeWaitMarginSeconds; +} + /// /// The telemetry provider: where the signals go, and what is listened to on the way. /// diff --git a/src/AgentCore.Application/Configuration/Schema/StateSlotConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/StateSlotConfiguration.cs index c7117ae9..f43281ee 100644 --- a/src/AgentCore.Application/Configuration/Schema/StateSlotConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/StateSlotConfiguration.cs @@ -68,4 +68,48 @@ public sealed record StateSlotConfiguration /// Gets the fixed value of the slot. It is set when the writer is . public JsonNode? Value { get; init; } + + /// + /// Gets the declaration that this slot's domain is read from a provider rather than hand-written + /// as , or when this document names none. + /// + public SlotVocabularyConfiguration? Vocabulary { get; init; } +} + +/// +/// A slot's domain, read from a provider at boot instead of written by hand as enum:. See +/// section 4 of the ambiguity-and-vocabulary design. +/// +public sealed record SlotVocabularyConfiguration +{ + /// The linker name used when the document names none. + public const string DefaultLinker = "exact"; + + /// The refresh interval used when the document sets none, in seconds. Boot only. + public const int DefaultRefreshSeconds = 0; + + /// The read limit used when the document sets none. + public const int DefaultMaxValues = 2000; + + /// Gets the provider the domain is read from. knowledge is the only member. + public required string From { get; init; } + + /// Gets the IStateValueLinker name. Only exact ships. + public string Linker { get; init; } = DefaultLinker; + + /// Gets how often the domain is re-read, in seconds. 0 means boot only. + public int RefreshSeconds { get; init; } = DefaultRefreshSeconds; + + /// + /// Gets the limit passed to the facet read. A read returning exactly this many fails startup: it + /// cannot be told from a truncation. + /// + public int MaxValues { get; init; } = DefaultMaxValues; + + /// + /// Gets whether every id in the collection, and every mention the extractor emits, is already + /// NFC. Lifts the refusal on a runtime that cannot compose Unicode, and carries the obligation + /// that every id and every mention really is already normalised. + /// + public bool AssumeNormalized { 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 7ccd50e8..8b7ae35f 100644 --- a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json +++ b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json @@ -198,6 +198,43 @@ }, "value": { "description": "writer: const. The fixed value of the slot." + }, + "vocabulary": { + "type": "object", + "description": "Declares that this slot's domain is read from a provider at boot, rather than hand-written as enum:. Absent by default.", + "additionalProperties": false, + "required": [ + "from" + ], + "properties": { + "from": { + "enum": [ + "knowledge" + ], + "description": "The provider to read the domain from. knowledge is the only member." + }, + "linker": { + "type": "string", + "minLength": 1, + "default": "exact", + "description": "The IStateValueLinker name. Only exact ships." + }, + "refreshSeconds": { + "type": "integer", + "default": 0, + "description": "How often the domain is re-read. 0 means boot only." + }, + "maxValues": { + "type": "integer", + "default": 2000, + "description": "The limit passed to the facet read. A read returning exactly this many fails startup: it cannot be told from a truncation." + }, + "assumeNormalized": { + "type": "boolean", + "default": false, + "description": "Declares that every id in the collection, and every mention the extractor emits, is already NFC. Lifts the refusal on a runtime that cannot compose Unicode." + } + } } }, "allOf": [ @@ -1174,6 +1211,33 @@ } } }, + "ambiguity": { + "type": "object", + "description": "How the knowledge search asks the caller which machine they meant. Absent by default, and absent means neither the probe nor the clarification ever runs.", + "additionalProperties": false, + "properties": { + "maxCandidates": { + "type": "integer", + "default": 6, + "description": "Above this many distinct values, the ask names none of them." + }, + "maxAsks": { + "type": "integer", + "default": 2, + "description": "The cap on each of a slot's two ask counters. 0 means never ask: the vocabulary and the gate still work." + }, + "probeDeadlineSeconds": { + "type": "integer", + "default": 5, + "description": "The probe's own budget. The main search keeps the store's own deadline." + }, + "probeWaitMarginSeconds": { + "type": "integer", + "default": 1, + "description": "How much longer than the probe a concurrent loser waits for the winner's payload." + } + } + }, "links": { "type": "object", "description": "How a card's links to other cards are read and followed. Writing the block turns link expansion on and requires a mapped fields.id; omitting it turns the feature off.", diff --git a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs index 5d0a6c44..d184bc32 100644 --- a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs +++ b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs @@ -29,6 +29,14 @@ namespace AgentCore.Application.Configuration.Validation; /// public static class ConfigurationValidator { + /// + /// 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 call site that carries no pointer + /// into the document. + /// + private const int MaxIntervalSeconds = int.MaxValue / 1000; + /// Runs checks 2 to 8 and returns everything they find. /// The bound document. /// Every error and every partial-coverage warning. @@ -84,6 +92,7 @@ public static ConfigurationValidationResult EvaluateStructure(AgentCoreConfigura CheckReferences(configuration, names, errors); CheckSlotWriters(configuration, errors); CheckKnowledgeScopeSlots(configuration, errors); + CheckVocabularyAndAmbiguity(configuration, errors, warnings); CheckGuardRules(configuration, errors); CheckExclusivity(configuration, errors, warnings); CheckReachability(configuration, errors); @@ -143,6 +152,32 @@ public static void ValidateToolReferences(AgentCoreConfiguration configuration, } } + /// + /// Resolves every slot's vocabulary.linker against the names the linker registry actually + /// serves, and throws when one names a linker nothing registered. + /// + /// + /// K12: a two-argument validator, run after the linker registry is built — the registry itself + /// lives in Application and is not reachable from here. A caller runs this after building it, + /// the same way runs after MCP discovery. + /// + /// The bound document. + /// Every linker name the registry serves. Always includes exact. + /// A slot names a linker nothing registered. + public static void ValidateLinkerNames(AgentCoreConfiguration configuration, IReadOnlySet registered) + { + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(registered); + + var errors = new List(); + CheckLinkerReferences(configuration, registered, errors); + + if (errors.Count > 0) + { + throw new ConfigurationLoadException(errors); + } + } + /// /// Resolves every skills: entry against the names the bound skills folder serves, and /// throws when one names a skill nothing serves. @@ -373,6 +408,30 @@ private static void CheckToolReferences(AgentCoreConfiguration configuration, IR } } + // --------------------------------------------------------------------------------------------- + // Check 2, linker names: K12's two-argument validator, run after the linker registry is built. + // --------------------------------------------------------------------------------------------- + /// Resolves every declared vocabulary.linker against what the registry serves. + /// The bound document. + /// Every linker name the registry serves. + /// The list every failure is added to. + private static void CheckLinkerReferences( + AgentCoreConfiguration configuration, IReadOnlySet registered, List errors) + { + foreach (var slot in configuration.State) + { + if (slot.Value.Vocabulary is not { } vocabulary || registered.Contains(vocabulary.Linker)) + { + continue; + } + + errors.Add(Reference( + ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(Pointer.State(slot.Key), "vocabulary"), "linker"), + $"the slot '{slot.Key}' declares vocabulary.linker: '{vocabulary.Linker}', which nothing " + + "registered. Register it with UseStateValueLinkers, or use 'exact'.")); + } + } + /// Resolves every agent's skills: entry against what the bound folder serves. /// The bound document. /// Every skill name the bound folder serves. @@ -521,32 +580,60 @@ private static void CheckKnowledgeScopeSlots( if (string.IsNullOrWhiteSpace(wildcard.Value)) { errors.Add(Reference( - "/providers/knowledge/scope/wildcard/value", + Pointer.WildcardValue, "the wildcard value is blank, so it names no payload value a card could carry.")); } if (wildcard.Facets.Count == 0) { errors.Add(Reference( - "/providers/knowledge/scope/wildcard/facets", + Pointer.WildcardFacets, "the wildcard names no facets, so it widens nothing. Name the reach facets, and " + "never an isolation facet such as a customer id.")); } } + // A wildcard without fromState is a supported shape: the deployment resolves its own facets + // and opens them as the host ambient, which the store still widens. See + // StateKnowledgeScope.Compose and KnowledgeStartup's K19 branch. Only the reverse is refused. if (scope.FromState.Count == 0) { return; } - if (scope.Wildcard is null) + if (scope.Wildcard is not { } widened) { errors.Add(Reference( - "/providers/knowledge/scope/wildcard", + Pointer.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.")); } + else + { + foreach (var facet in widened.Facets) + { + if (!scope.FromState.Contains(facet, StringComparer.Ordinal)) + { + errors.Add(Reference( + Pointer.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 name in scope.FromState) + { + if (!widened.Facets.Contains(name, StringComparer.Ordinal)) + { + errors.Add(Reference( + Pointer.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.")); + } + } + } if (configuration.Extractor is null) { @@ -558,19 +645,10 @@ private static void CheckKnowledgeScopeSlots( foreach (var name in scope.FromState) { - if (scope.Wildcard is { } declared - && !declared.Facets.Contains(name, StringComparer.Ordinal)) - { - errors.Add(Reference( - "/providers/knowledge/scope/wildcard/facets", - $"fromState names '{name}' and wildcard.facets does not, so an unfilled '{name}' " - + "would be searched for the literal wildcard rather than widened by it.")); - } - if (!configuration.State.TryGetValue(name, out var slot)) { errors.Add(Reference( - "/providers/knowledge/scope/fromState", + Pointer.FromState, $"fromState names the slot '{name}', which this document does not declare.")); continue; } @@ -602,17 +680,187 @@ private static void CheckKnowledgeScopeSlots( + "scope mid-call.")); } - if (slot.EnumValues is not { Count: > 0 }) + if (slot.EnumValues is not { Count: > 0 } && slot.Vocabulary is null) { 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.")); + $"the facet slot '{name}' declares neither enum nor vocabulary. 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.")); } } } + // --------------------------------------------------------------------------------------------- + // Check 2, vocabulary and ambiguity: section 10 of the ambiguity-and-vocabulary design. + // --------------------------------------------------------------------------------------------- + + /// Refuses a vocabulary: or ambiguity: block that could not do what it declares. + /// + /// Unlike , the slot-level rules here do not depend on the + /// slot being named in scope.fromState: a slot may declare vocabulary: without ever + /// being read by the scope, and that mismatch is itself one of the refusals below. + /// + private static void CheckVocabularyAndAmbiguity( + AgentCoreConfiguration configuration, List errors, List warnings) + { + var knowledge = configuration.Providers?.Knowledge; + var fromState = knowledge?.Scope.FromState ?? []; + var anyVocabulary = false; + + foreach (var entry in configuration.State) + { + if (entry.Value.Vocabulary is not { } vocabulary) + { + continue; + } + + anyVocabulary = true; + var pointer = Pointer.State(entry.Key); + var vocabularyPointer = ConfigurationError.AppendPointer(pointer, "vocabulary"); + + if (entry.Value.EnumValues is { Count: > 0 }) + { + errors.Add(Reference( + vocabularyPointer, + $"the slot '{entry.Key}' declares both enum and vocabulary. enum is a fixed, " + + "hand-written list; vocabulary reads the domain from a provider at boot. A slot " + + "cannot have both.")); + } + + if (entry.Value.Value is not null) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "value"), + $"the slot '{entry.Key}' declares both value and vocabulary. value is writer: " + + "const's fixed value; vocabulary reads a domain the extractor fills at runtime. " + + "A slot cannot have both.")); + } + + if (!fromState.Contains(entry.Key, StringComparer.Ordinal)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(vocabularyPointer, "from"), + $"the slot '{entry.Key}' declares vocabulary.from: knowledge, and " + + "providers.knowledge.scope.fromState does not name it. The gate and the linker " + + "would then hold a domain no turn's scope ever narrows by.")); + } + + CheckRange( + vocabulary.MaxValues, + 2, + int.MaxValue, + ConfigurationError.AppendPointer(vocabularyPointer, "maxValues"), + $"vocabulary.maxValues on the slot '{entry.Key}'", + "A read of fewer than two values could never be told apart from a truncated one.", + errors); + + CheckRange( + vocabulary.RefreshSeconds, + 0, + MaxIntervalSeconds, + ConfigurationError.AppendPointer(vocabularyPointer, "refreshSeconds"), + $"vocabulary.refreshSeconds on the slot '{entry.Key}'", + "0 means boot only. A negative interval matches AgentCoreBoot's own " + + "{ RefreshSeconds: > 0 } guard on nothing, so the slot would silently read once at " + + "boot and never refresh again, and one above the range throws out of the " + + "PeriodicTimer VocabularyRefreshService builds from it.", + errors); + } + + if (anyVocabulary && knowledge?.Ambiguity is null) + { + errors.Add(Reference( + Pointer.Ambiguity, + "a slot declares vocabulary, and providers.knowledge.ambiguity is absent. vocabulary " + + "installs the linker, which can return Ambiguous — an outcome a plain enum gate never " + + "produces — and without ambiguity there is no channel to tell anyone.")); + } + + if (knowledge?.Ambiguity is not { } ambiguity) + { + return; + } + + if (knowledge.Mapper is not null) + { + errors.Add(Reference( + Pointer.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.Scope.Wildcard is null) + { + errors.Add(Reference( + Pointer.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.")); + } + + CheckRange( + ambiguity.MaxCandidates, + 2, + int.MaxValue, + ConfigurationError.AppendPointer(Pointer.Ambiguity, "maxCandidates"), + "ambiguity.maxCandidates", + "Below 2, the ask could never name a spread of candidates.", + errors); + + CheckRange( + ambiguity.MaxAsks, + 0, + int.MaxValue, + ConfigurationError.AppendPointer(Pointer.Ambiguity, "maxAsks"), + "ambiguity.maxAsks", + "0 is legal and means gate only; a negative count is not.", + errors); + + CheckRange( + ambiguity.ProbeDeadlineSeconds, + 1, + MaxIntervalSeconds, + ConfigurationError.AppendPointer(Pointer.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(Pointer.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); + + // 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 (fromState.Count <= 1) + { + warnings.Add(Reference( + Pointer.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.")); + } + + if (configuration.Graph is not null) + { + warnings.Add(Reference( + Pointer.Ambiguity, + "providers.knowledge.ambiguity is declared on a graph: document. The clarification's " + + "turn-context guard only passes on a session whose row carries history, which a " + + "graph run does not, so channel 1 is silent here.")); + } + } + // --------------------------------------------------------------------------------------------- // Check 3: one writer for each slot. // --------------------------------------------------------------------------------------------- @@ -1105,6 +1353,45 @@ private static HashSet Reach(string root, Dictionary new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.ReferenceResolution }; + private static ConfigurationError Range(string pointer, string message) + => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.ValueRange }; + + /// 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 call 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. + /// + private static void CheckRange( + int value, + int min, + int max, + string pointer, + string subject, + string why, + List errors) + { + if (value >= min && value <= max) + { + return; + } + + 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); + + errors.Add(Range( + pointer, + $"{subject} is {value.ToString(CultureInfo.InvariantCulture)}, and {accepted}. {why}")); + } + private static ConfigurationError Writers(string pointer, string message) => new() { Pointer = pointer, Message = message, Check = ConfigurationCheck.SlotWriters }; @@ -1148,6 +1435,18 @@ public static DeclaredNames From(AgentCoreConfiguration configuration) private static class Pointer { + 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"; + public static string State(string slot) => ConfigurationError.AppendPointer("/state", slot); public static string Guard(string name) => ConfigurationError.AppendPointer("/guards", name); diff --git a/src/AgentCore.Application/Diagnostics/Log.cs b/src/AgentCore.Application/Diagnostics/Log.cs index 2f0d504f..0e47a79d 100644 --- a/src/AgentCore.Application/Diagnostics/Log.cs +++ b/src/AgentCore.Application/Diagnostics/Log.cs @@ -191,4 +191,31 @@ public static partial void KnowledgeScopeComposed( string callId, 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 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 call continues.")] + public static partial void KnowledgeProbeFailed(ILogger logger, string agent, string facet, Exception exception); } diff --git a/src/AgentCore.Application/Knowledge/CompositeKnowledgeStoreFactory.cs b/src/AgentCore.Application/Knowledge/CompositeKnowledgeStoreFactory.cs index 3c514cdd..37a951be 100644 --- a/src/AgentCore.Application/Knowledge/CompositeKnowledgeStoreFactory.cs +++ b/src/AgentCore.Application/Knowledge/CompositeKnowledgeStoreFactory.cs @@ -53,9 +53,8 @@ public static class CompositeKnowledgeStoreFactory 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. 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."); + + "template, so AgentCore does not know where this collection keeps its facets. " + + ScopeTemplate.WriteOneAdvice); } if (entry.Mapper is null diff --git a/src/AgentCore.Application/Knowledge/KnowledgeCancellation.cs b/src/AgentCore.Application/Knowledge/KnowledgeCancellation.cs new file mode 100644 index 00000000..73c46fc3 --- /dev/null +++ b/src/AgentCore.Application/Knowledge/KnowledgeCancellation.cs @@ -0,0 +1,34 @@ +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 +/// call nothing, while a failure is reported to the model and logged. +/// +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) + => 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) + => !timeout.IsCancellationRequested && ByCaller(failure, cancellationToken); +} diff --git a/src/AgentCore.Application/Knowledge/KnowledgeNotices.cs b/src/AgentCore.Application/Knowledge/KnowledgeNotices.cs new file mode 100644 index 00000000..d1516266 --- /dev/null +++ b/src/AgentCore.Application/Knowledge/KnowledgeNotices.cs @@ -0,0 +1,35 @@ +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 +{ + /// 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 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 call 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 }; +} diff --git a/src/AgentCore.Application/Knowledge/KnowledgeProbe.cs b/src/AgentCore.Application/Knowledge/KnowledgeProbe.cs new file mode 100644 index 00000000..8532964d --- /dev/null +++ b/src/AgentCore.Application/Knowledge/KnowledgeProbe.cs @@ -0,0 +1,357 @@ +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. Channel 2 of the ambiguity design — 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 +{ + /// Runs the probe. + /// The store the probe's own second search reads. + /// The agent's resolved knowledge: block. + /// The live scope the main search just ran under. + /// The id of the agent that asked, for the log line. + /// The search text the framework composed. + /// Where the probe's own log events go. + /// 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( + IKnowledgeRetrievalPort port, + ResolvedKnowledge knowledge, + KnowledgeScope scope, + string agent, + string query, + ILogger logger, + CancellationToken cancellationToken) + { + // K42: a nested tool call strips the holder from the ambient, so a delegated run's own search + // cannot latch, count or record — but a scoped run still owes the caller the notice. + if (TurnAmbients.Current?.Clarifications is not { } clarifications) + { + return [KnowledgeNotices.Of(KnowledgeNotices.Empty)]; + } + + var wiring = knowledge.Clarification; + + // 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. + if (wiring.Ambiguity is not { } ambiguity + || wiring.WildcardValue is not { } wildcardValue + || wiring.WildcardFacets is not { Count: > 0 } wildcardFacets + || wiring.Template is not { } template) + { + 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.FromState, wildcardValue, wildcardFacets, scope, ambiguity, clarifications) + is not { } facet) + { + return [KnowledgeNotices.Of(KnowledgeNotices.Empty)]; + } + + var probe = clarifications.ClaimProbe(); + if (!probe.Won) + { + return await ReplayAsync(probe, ambiguity, cancellationToken).ConfigureAwait(false); + } + + // 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(ambiguity.ProbeDeadlineSeconds)); + using var deadline = + CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeout.Token); + + IReadOnlyList probeCards; + try + { + using var narrowed = KnowledgeScopeScope.Open(WithoutFacet(scope, facet)); + + var started = Stopwatch.GetTimestamp(); + probeCards = await port.SearchAsync(query, deadline.Token).ConfigureAwait(false); + + if (logger.IsEnabled(LogLevel.Debug)) + { + // Filed while the narrowed scope is still open, so the record names the scope this + // second store call actually ran under. Without it an operator sizing store load + // sees one record per turn for two calls. + var record = KnowledgeSearchRecord.Of( + agent, + knowledge, + query, + probeCards, + Stopwatch.GetElapsedTime(started).TotalMilliseconds, + failure: null).ForLog(); + + Log.KnowledgeRetrieved(logger, agent, probeCards.Count, record); + } + } + 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(logger, agent, facet, failure); + + return Publish(probe, KnowledgeNotices.Empty); + } + + return Name(probeCards, template, ambiguity, wiring, wildcardValue, facet, agent, logger, clarifications, probe); + } + finally + { + probe.Fail(); + } + } + + /// 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 + { + 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)]; + } + } + + /// §8 steps 5-6: reads the candidates out of the probe's cards and decides what to say. + private static IReadOnlyList Name( + IReadOnlyList probeCards, + ScopeTemplate template, + KnowledgeAmbiguityConfiguration ambiguity, + ResolvedClarification wiring, + string wildcardValue, + string facet, + string agent, + ILogger logger, + Clarifications clarifications, + Clarifications.Probe probe) + { + // §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 = template.Resolve(facet); + SortedSet union = new(StringComparer.Ordinal); + + foreach (var card in probeCards) + { + foreach (var value in FacetValues(card, path)) + { + if (!string.Equals(value, wildcardValue, StringComparison.Ordinal)) + { + union.Add(value); + } + } + } + + Log.KnowledgeProbeRan(logger, agent, facet, union.Count); + + 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. + var wouldName = Clarifications.LastNamed.For(union, 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. + var carriesHistory = TurnAmbients.Current?.Context?.CarriesHistory ?? false; + + // Whether the note repeats what was last named, and the pending list and record that follow + // 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 call slip between the two. + var repeats = false; + + clarifications.Update(facet, s => + { + repeats = wouldName.Names(s.EffectiveLastNamed); + + if (repeats) + { + return; + } + + // K41: the probe sets a pending list only where there is none. The linker's own list is + // what the caller was actually answering, and a search's guess must never replace it. + s.Pending ??= candidates; + + if (carriesHistory) + { + s.LastNamed = wouldName; + } + }); + + if (repeats) + { + return Publish(probe, KnowledgeNotices.Empty); + } + + var description = ClarificationText.DescriptionOf(facet, wiring.SlotDescriptions); + + return Publish(probe, ClarificationText.Note(description, candidates, ambiguity.MaxCandidates)); + } + + /// 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; + } + + /// + /// §8 step 3: the first facet, in fromState declaration order, the wildcard filled and that + /// dropping would not empty the scope, skip a slot at its ask cap, or repeat channel 1's own + /// question this turn. + /// + private static string? DroppableFacet( + IReadOnlyList fromState, + string wildcardValue, + IReadOnlyList wildcardFacets, + KnowledgeScope scope, + KnowledgeAmbiguityConfiguration ambiguity, + 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) + { + return null; + } + + foreach (var name in fromState) + { + // 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 (!wildcardFacets.Contains(name, StringComparer.Ordinal) + || !scope.Facets.TryGetValue(name, out var value) + || !string.Equals(value, wildcardValue, StringComparison.Ordinal) + || (scope.Origins.TryGetValue(name, out var origin) + && origin != KnowledgeFacetOrigin.Wildcard)) + { + continue; + } + + var snapshot = clarifications.Read(name); + + // K22: the probe's own counter is monotone and capped at maxAsks. K41: channel 1 already + // asked about this slot this turn, so the probe moves on rather than paying for a search + // it would then abandon. + if (snapshot.ProbeAsks >= ambiguity.MaxAsks || snapshot.AskedThisTurn) + { + continue; + } + + return name; + } + + return null; + } + + /// 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); + + Dictionary origins = new(scope.Origins, ComparerOf(scope.Origins)); + origins.Remove(facet); + + return scope with { Facets = facets, Origins = origins }; + } + + /// 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; + + /// + /// §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); + + if (current is string single) + { + yield return single; + yield break; + } + + if (current is IReadOnlyList many) + { + foreach (var item in many) + { + 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 da9e1f01..ad43f34c 100644 --- a/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs +++ b/src/AgentCore.Application/Knowledge/KnowledgeProviderFactory.cs @@ -16,32 +16,6 @@ namespace AgentCore.Application.Knowledge; /// internal static class KnowledgeProviderFactory { - /// - /// What the model is told when the search itself failed. - /// - private const string UnreachableNotice = - "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. - /// - private const string NoScopeNotice = - "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 call by announcing an empty knowledge base. - /// - private const string EmptyNotice = - "The knowledge base holds nothing for this question. Say so, and do not answer from memory."; - - /// The source name every notice carries, so the model can never cite one as a card. - internal const string NoticeSourceName = "agentcore:notice"; - /// /// The scope an agent that declares scoped: false searches under. /// @@ -99,77 +73,63 @@ internal static AIContextProvider Create( // customer's cards. if (knowledge.Scoped && KnowledgeScopeScope.Current is not { Facets.Count: > 0 }) { - return [Notice(NoScopeNotice)]; + return [KnowledgeNotices.Of(KnowledgeNotices.NoScope)]; } using var whole = knowledge.Scoped ? null : KnowledgeScopeScope.Open(WholeCorpus); var started = Stopwatch.GetTimestamp(); + // Held from the moment the main search returns, so a failure raised by anything after it — + // the probe's own second search included — is still recorded against the time the main + // search took, rather than against however long the probe went on to run. + double? searched = null; + try { var cards = await port.SearchAsync(query, cancellationToken).ConfigureAwait(false); + searched = Stopwatch.GetElapsedTime(started).TotalMilliseconds; if (logger.IsEnabled(LogLevel.Debug)) { - var record = Record(agent, knowledge, query, cards, started, failure: null).ForLog(); + var record = KnowledgeSearchRecord + .Of(agent, knowledge, query, cards, searched.Value, failure: null) + .ForLog(); + Log.KnowledgeRetrieved(logger, agent, cards.Count, record); } - // Only a scope with at least one facet gets the notice. An unscoped agent opened - // WholeCorpus, and its empty search stays an empty list. + // §8 step 1-2: the probe runs only for a tool-mode search that cleared no card at + // all (K13) and only for a scoped agent — an unscoped agent opened WholeCorpus, which + // holds no facets, and its empty search stays an empty list, exactly as today (K19). if (cards.Count == 0 && knowledge.Mode == KnowledgeMode.Tool - && KnowledgeScopeScope.Current is { Facets.Count: > 0 }) + && KnowledgeScopeScope.Current is { Facets.Count: > 0 } scope) { - return [Notice(EmptyNotice)]; + return await KnowledgeProbe + .RunAsync(port, knowledge, scope, agent, query, logger, cancellationToken) + .ConfigureAwait(false); } var shown = Kept(cards, knowledge); - Cite(shown, knowledge, citations); return Map(shown, knowledge, citations); } - catch (Exception failure) when (!CallerCancelled(failure, cancellationToken)) + catch (Exception failure) when (!KnowledgeCancellation.ByCaller(failure, cancellationToken)) { - var record = Record(agent, knowledge, query, [], started, failure).ForLog(); + var latency = searched ?? Stopwatch.GetElapsedTime(started).TotalMilliseconds; + var record = KnowledgeSearchRecord + .Of(agent, knowledge, query, [], latency, failure) + .ForLog(); + Log.KnowledgeRetrievalFailed(logger, agent, record, failure); - return [Notice(UnreachableNotice)]; + return [KnowledgeNotices.Of(KnowledgeNotices.Unreachable)]; } } } - /// Whether a failure is the caller ending the turn, rather than the retrieval failing. - private static bool CallerCancelled(Exception failure, CancellationToken cancellationToken) - => failure is OperationCanceledException && cancellationToken.IsCancellationRequested; - - /// Reads one finished retrieval into the record an operator debugs an outage from. - /// The id of the agent that asked. - /// The agent's resolved knowledge: block. - /// The search text the framework composed. - /// What the store returned, or empty when it threw. - /// The timestamp taken immediately before the port call. - /// What the port threw, or when it answered. - /// The record. - private static KnowledgeAuditRecord Record( - string agent, - ResolvedKnowledge knowledge, - string query, - IReadOnlyList cards, - long started, - Exception? failure) - => KnowledgeAuditRecord.For( - turnId: null, - agent, - knowledge.Mode, - query, - KnowledgeScopeScope.Current, - cards, - Stopwatch.GetElapsedTime(started).TotalMilliseconds, - failure); - /// 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. @@ -234,10 +194,4 @@ private static List Kept(IReadOnlyList cards, Reso return mapped; } - - /// Wraps one sentence for the model in the shape the framework injects. - /// What the model is told. - /// The result. - private static TextSearchProvider.TextSearchResult Notice(string text) - => new() { Text = text, SourceName = NoticeSourceName }; } diff --git a/src/AgentCore.Application/Knowledge/KnowledgeSearchRecord.cs b/src/AgentCore.Application/Knowledge/KnowledgeSearchRecord.cs new file mode 100644 index 00000000..f1bc3f14 --- /dev/null +++ b/src/AgentCore.Application/Knowledge/KnowledgeSearchRecord.cs @@ -0,0 +1,41 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Runtime; +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 +{ + /// Builds the record. + /// The id of the agent that asked. + /// The agent's resolved knowledge: block. + /// The search text the framework composed. + /// 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. + /// + /// The scope comes from the live ambient, so a caller has to build this while the scope the call + /// ran under is still open. The probe's second search opens a narrowed scope of its own, and its + /// record is meant to name that one rather than the scope the main search used. + /// + internal static KnowledgeAuditRecord Of( + string agent, + ResolvedKnowledge knowledge, + string query, + IReadOnlyList cards, + double latencyMs, + Exception? failure) + => KnowledgeAuditRecord.For( + turnId: null, + agent, + knowledge.Mode, + query, + KnowledgeScopeScope.Current, + cards, + latencyMs, + failure); +} diff --git a/src/AgentCore.Application/Ports/IFacetVocabularyPort.cs b/src/AgentCore.Application/Ports/IFacetVocabularyPort.cs new file mode 100644 index 00000000..4a4dc93c --- /dev/null +++ b/src/AgentCore.Application/Ports/IFacetVocabularyPort.cs @@ -0,0 +1,17 @@ +namespace AgentCore.Application.Ports; + +/// +/// Reads the distinct values a store holds at one payload path — the vocabulary a +/// vocabulary: slot gates writes against and links mentions to. +/// +public interface IFacetVocabularyPort +{ + /// Reads the distinct values stored at one payload path. + /// The payload path, already resolved from scope.template. + /// The most values to return. A result of exactly this size is a truncation. + /// Cancels the read. + ValueTask> ReadAsync( + string path, + int limit, + CancellationToken cancellationToken = default); +} diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index 506ae994..d28ca41c 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -58,6 +58,16 @@ AgentCore.Application.Call.CallInput.Utterance.Text.get -> string! AgentCore.Application.Call.CallInput.Utterance.Text.init -> void AgentCore.Application.Call.CallInput.Utterance.Utterance(string! Text, string! Language, bool IsFinal) -> void AgentCore.Application.Call.CallSpeechPairing +AgentCore.Application.Calls.CallClarificationState +AgentCore.Application.Calls.CallClarificationState.$() -> AgentCore.Application.Calls.CallClarificationState! +AgentCore.Application.Calls.CallClarificationState.CallClarificationState() -> void +AgentCore.Application.Calls.CallClarificationState.Equals(AgentCore.Application.Calls.CallClarificationState? other) -> bool +AgentCore.Application.Calls.CallClarificationState.NamedAsks.get -> int +AgentCore.Application.Calls.CallClarificationState.NamedAsks.init -> void +AgentCore.Application.Calls.CallClarificationState.ProbeAsks.get -> int +AgentCore.Application.Calls.CallClarificationState.ProbeAsks.init -> void +AgentCore.Application.Calls.CallClarificationState.ResetSpent.get -> bool +AgentCore.Application.Calls.CallClarificationState.ResetSpent.init -> void AgentCore.Application.Calls.CallCursor AgentCore.Application.Calls.CallPage AgentCore.Application.Calls.CallPage.$() -> AgentCore.Application.Calls.CallPage! @@ -92,6 +102,8 @@ AgentCore.Application.Calls.CallRecord.Title.init -> void AgentCore.Application.Calls.CallSessionState AgentCore.Application.Calls.CallSessionState.$() -> AgentCore.Application.Calls.CallSessionState! AgentCore.Application.Calls.CallSessionState.CallSessionState() -> void +AgentCore.Application.Calls.CallSessionState.Clarifications.get -> System.Collections.Generic.IReadOnlyDictionary! +AgentCore.Application.Calls.CallSessionState.Clarifications.init -> void AgentCore.Application.Calls.CallSessionState.Equals(AgentCore.Application.Calls.CallSessionState? other) -> bool AgentCore.Application.Calls.CallSessionState.IsComplete.get -> bool AgentCore.Application.Calls.CallSessionState.IsComplete.init -> void @@ -173,10 +185,28 @@ AgentCore.Application.Configuration.Compilation.CompiledAgentShape.PatternGraph AgentCore.Application.Configuration.Compilation.CompiledAgentShape.Policy = 1 -> AgentCore.Application.Configuration.Compilation.CompiledAgentShape AgentCore.Application.Configuration.Compilation.CompiledAgentShape.SingleAgent = 0 -> AgentCore.Application.Configuration.Compilation.CompiledAgentShape AgentCore.Application.Configuration.Compilation.ConfigurationCompiler +AgentCore.Application.Configuration.Compilation.ResolvedClarification +AgentCore.Application.Configuration.Compilation.ResolvedClarification.$() -> AgentCore.Application.Configuration.Compilation.ResolvedClarification! +AgentCore.Application.Configuration.Compilation.ResolvedClarification.Ambiguity.get -> AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? +AgentCore.Application.Configuration.Compilation.ResolvedClarification.Ambiguity.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedClarification.Equals(AgentCore.Application.Configuration.Compilation.ResolvedClarification? other) -> bool +AgentCore.Application.Configuration.Compilation.ResolvedClarification.FromState.get -> System.Collections.Generic.IReadOnlyList! +AgentCore.Application.Configuration.Compilation.ResolvedClarification.FromState.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedClarification.ResolvedClarification() -> void +AgentCore.Application.Configuration.Compilation.ResolvedClarification.SlotDescriptions.get -> System.Collections.Generic.IReadOnlyDictionary! +AgentCore.Application.Configuration.Compilation.ResolvedClarification.SlotDescriptions.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedClarification.Template.get -> AgentCore.Application.Configuration.Parsing.ScopeTemplate? +AgentCore.Application.Configuration.Compilation.ResolvedClarification.Template.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardFacets.get -> System.Collections.Generic.IReadOnlyList! +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.ResolvedKnowledge AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.$() -> AgentCore.Application.Configuration.Compilation.ResolvedKnowledge! AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Citations.get -> bool AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Citations.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Clarification.get -> AgentCore.Application.Configuration.Compilation.ResolvedClarification! +AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Clarification.init -> void AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Deconstruct(out AgentCore.Application.Configuration.Schema.KnowledgeMode Mode, out int Limit, out bool Citations, out bool Scoped) -> void AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Equals(AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? other) -> bool AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Limit.get -> int @@ -196,6 +226,7 @@ AgentCore.Application.Configuration.Parsing.ConfigurationCheck.Reachability = 6 AgentCore.Application.Configuration.Parsing.ConfigurationCheck.ReferenceResolution = 2 -> AgentCore.Application.Configuration.Parsing.ConfigurationCheck AgentCore.Application.Configuration.Parsing.ConfigurationCheck.SlotWriters = 3 -> AgentCore.Application.Configuration.Parsing.ConfigurationCheck AgentCore.Application.Configuration.Parsing.ConfigurationCheck.Syntax = 0 -> AgentCore.Application.Configuration.Parsing.ConfigurationCheck +AgentCore.Application.Configuration.Parsing.ConfigurationCheck.ValueRange = 9 -> AgentCore.Application.Configuration.Parsing.ConfigurationCheck AgentCore.Application.Configuration.Parsing.ConfigurationError AgentCore.Application.Configuration.Parsing.ConfigurationError.$() -> AgentCore.Application.Configuration.Parsing.ConfigurationError! AgentCore.Application.Configuration.Parsing.ConfigurationError.Check.get -> AgentCore.Application.Configuration.Parsing.ConfigurationCheck @@ -222,6 +253,11 @@ AgentCore.Application.Configuration.Parsing.ConfigurationLoadException.Errors.ge AgentCore.Application.Configuration.Parsing.ConfigurationLoadException.Pointer.get -> string! AgentCore.Application.Configuration.Parsing.ConfigurationLoader AgentCore.Application.Configuration.Parsing.ConfigurationSchemaValidator +AgentCore.Application.Configuration.Parsing.ScopeTemplate +AgentCore.Application.Configuration.Parsing.ScopeTemplate.$() -> AgentCore.Application.Configuration.Parsing.ScopeTemplate! +AgentCore.Application.Configuration.Parsing.ScopeTemplate.Equals(AgentCore.Application.Configuration.Parsing.ScopeTemplate? other) -> bool +AgentCore.Application.Configuration.Parsing.ScopeTemplate.Raw.get -> string! +AgentCore.Application.Configuration.Parsing.ScopeTemplate.Resolve(string! key) -> string! AgentCore.Application.Configuration.Parsing.SecretReference AgentCore.Application.Configuration.Parsing.SecretReference.$() -> AgentCore.Application.Configuration.Parsing.SecretReference! AgentCore.Application.Configuration.Parsing.SecretReference.Deconstruct(out string! Name, out int Start, out int Length) -> void @@ -416,6 +452,18 @@ AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.Method.get - AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.Method.init -> void AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.Url.get -> string! AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.Url.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.$() -> AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration! +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.Equals(AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? other) -> bool +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.KnowledgeAmbiguityConfiguration() -> void +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.MaxAsks.get -> int +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.MaxAsks.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.MaxCandidates.get -> int +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.MaxCandidates.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ProbeDeadlineSeconds.get -> int +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ProbeDeadlineSeconds.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ProbeWaitMarginSeconds.get -> int +AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ProbeWaitMarginSeconds.init -> void AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.$() -> AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration! AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.Authority.get -> string? @@ -453,6 +501,8 @@ AgentCore.Application.Configuration.Schema.KnowledgeMode.Prefetch = 0 -> AgentCo AgentCore.Application.Configuration.Schema.KnowledgeMode.Tool = 1 -> AgentCore.Application.Configuration.Schema.KnowledgeMode AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.$() -> AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration! +AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.Ambiguity.get -> AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? +AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.Ambiguity.init -> void AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.Analyzer.get -> string! AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.Analyzer.init -> void AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.Citation.get -> string! @@ -593,6 +643,20 @@ AgentCore.Application.Configuration.Schema.ProvidersConfiguration.Telemetry.init AgentCore.Application.Configuration.Schema.ProvidersConfiguration.Telephony.get -> AgentCore.Application.Configuration.Schema.VendorProviderConfiguration? AgentCore.Application.Configuration.Schema.ProvidersConfiguration.Telephony.init -> void AgentCore.Application.Configuration.Schema.ReservedStateSlots +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.$() -> AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration! +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.AssumeNormalized.get -> bool +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.AssumeNormalized.init -> void +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.Equals(AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration? other) -> bool +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.From.get -> string! +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.From.init -> void +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.Linker.get -> string! +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.Linker.init -> void +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.MaxValues.get -> int +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.MaxValues.init -> void +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.RefreshSeconds.get -> int +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.RefreshSeconds.init -> void +AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.SlotVocabularyConfiguration() -> void AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.$() -> AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration! AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.Equals(AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration? other) -> bool @@ -644,6 +708,8 @@ AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Type.get -> Ag AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Type.init -> void AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Value.get -> System.Text.Json.Nodes.JsonNode? AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Value.init -> void +AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Vocabulary.get -> AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration? +AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Vocabulary.init -> void AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Writer.get -> AgentCore.Application.Configuration.Schema.StateWriter AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Writer.init -> void AgentCore.Application.Configuration.Schema.StateSlotType @@ -900,6 +966,8 @@ AgentCore.Application.Ports.IEmbeddingGeneratorAdapter AgentCore.Application.Ports.IEmbeddingGeneratorAdapter.CreateGeneratorAsync(AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration! entry, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!>!> AgentCore.Application.Ports.IEvaluationScorePublisher AgentCore.Application.Ports.IEvaluationScorePublisher.PublishAsync(AgentCore.Application.Evaluation.EvaluationScore! score, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Ports.IFacetVocabularyPort +AgentCore.Application.Ports.IFacetVocabularyPort.ReadAsync(string! path, int limit, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Ports.IKnowledgeRetrievalPort AgentCore.Application.Ports.IKnowledgeRetrievalPort.SearchAsync(string! query, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Ports.IKnowledgeStoreAdapter @@ -994,7 +1062,7 @@ AgentCore.Application.Runtime.CallSession.Stage.get -> string! AgentCore.Application.Runtime.CallSession.State.get -> AgentCore.Application.State.StateDocument! AgentCore.Application.Runtime.CallSession.Transcript.get -> System.Collections.Generic.IReadOnlyList! AgentCore.Application.Runtime.CallSessionFactory -AgentCore.Application.Runtime.CallSessionFactory.CallSessionFactory(AgentCore.Application.Configuration.Compilation.CompiledAgent! compiled, AgentCore.Application.Configuration.Validation.IGuardEvaluator! guards, AgentCore.Application.State.StateExtractor? extractor = null, System.TimeProvider? timeProvider = null, Microsoft.Extensions.Logging.ILogger? logger = null, System.Collections.Generic.IEnumerable? observers = null) -> void +AgentCore.Application.Runtime.CallSessionFactory.CallSessionFactory(AgentCore.Application.Configuration.Compilation.CompiledAgent! compiled, AgentCore.Application.Configuration.Validation.IGuardEvaluator! guards, AgentCore.Application.State.StateExtractor? extractor = null, System.TimeProvider? timeProvider = null, Microsoft.Extensions.Logging.ILogger? logger = null, System.Collections.Generic.IEnumerable? observers = null, AgentCore.Application.State.VocabularyCache? vocabulary = null) -> void AgentCore.Application.Runtime.CallSessionFactory.Create(string? callId = null, AgentCore.Application.Calls.CallSessionState? state = null) -> AgentCore.Application.Runtime.CallSession! AgentCore.Application.Runtime.CallSourceScope AgentCore.Application.Runtime.CallStateScope @@ -1044,6 +1112,26 @@ AgentCore.Application.State.ConstStateWriter AgentCore.Application.State.CounterStateWriter AgentCore.Application.State.CounterStateWriter.Apply(AgentCore.Application.State.StateDocument! state) -> int AgentCore.Application.State.CounterStateWriter.CounterStateWriter(AgentCore.Application.Configuration.Validation.IGuardEvaluator! rules) -> void +AgentCore.Application.State.ExactStateValueLinker +AgentCore.Application.State.ExactStateValueLinker.ExactStateValueLinker() -> void +AgentCore.Application.State.ExactStateValueLinker.Link(string! mention, AgentCore.Application.State.VocabularyView! vocabulary, System.Collections.Generic.IReadOnlySet! lastNamed) -> AgentCore.Application.State.LinkResult! +AgentCore.Application.State.ExactStateValueLinker.Name.get -> string! +AgentCore.Application.State.IStateValueLinker +AgentCore.Application.State.IStateValueLinker.Link(string! mention, AgentCore.Application.State.VocabularyView! vocabulary, System.Collections.Generic.IReadOnlySet! lastNamed) -> AgentCore.Application.State.LinkResult! +AgentCore.Application.State.IStateValueLinker.Name.get -> string! +AgentCore.Application.State.LinkOutcome +AgentCore.Application.State.LinkOutcome.Ambiguous = 2 -> AgentCore.Application.State.LinkOutcome +AgentCore.Application.State.LinkOutcome.Linked = 1 -> AgentCore.Application.State.LinkOutcome +AgentCore.Application.State.LinkOutcome.NoMatch = 0 -> AgentCore.Application.State.LinkOutcome +AgentCore.Application.State.LinkResult +AgentCore.Application.State.LinkResult.$() -> AgentCore.Application.State.LinkResult! +AgentCore.Application.State.LinkResult.Candidates.get -> System.Collections.Generic.IReadOnlyList! +AgentCore.Application.State.LinkResult.Candidates.init -> void +AgentCore.Application.State.LinkResult.Deconstruct(out AgentCore.Application.State.LinkOutcome Outcome, out System.Collections.Generic.IReadOnlyList! Candidates) -> void +AgentCore.Application.State.LinkResult.Equals(AgentCore.Application.State.LinkResult? other) -> bool +AgentCore.Application.State.LinkResult.LinkResult(AgentCore.Application.State.LinkOutcome Outcome, System.Collections.Generic.IReadOnlyList! Candidates) -> void +AgentCore.Application.State.LinkResult.Outcome.get -> AgentCore.Application.State.LinkOutcome +AgentCore.Application.State.LinkResult.Outcome.init -> void AgentCore.Application.State.StateDocument AgentCore.Application.State.StateDocument.CallDurationSeconds.get -> double AgentCore.Application.State.StateDocument.CallDurationSeconds.set -> void @@ -1054,7 +1142,7 @@ AgentCore.Application.State.StateDocument.SlotNames.get -> System.Collections.Ge AgentCore.Application.State.StateDocument.Snapshot() -> System.Collections.Generic.IReadOnlyDictionary! AgentCore.Application.State.StateDocument.Stage.get -> string! AgentCore.Application.State.StateDocument.Stage.set -> void -AgentCore.Application.State.StateDocument.StateDocument(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, string? stage = null) -> void +AgentCore.Application.State.StateDocument.StateDocument(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, string? stage = null, System.Collections.Generic.IReadOnlyDictionary? vocabulary = null) -> void AgentCore.Application.State.StateDocument.TryWrite(string! slot, System.Text.Json.Nodes.JsonNode? value) -> bool AgentCore.Application.State.StateDocument.TurnIndex.get -> int AgentCore.Application.State.StateDocument.TurnIndex.set -> void @@ -1084,6 +1172,24 @@ AgentCore.Application.State.StateExtractor.Write(AgentCore.Application.State.Sta AgentCore.Application.State.StateValueCoercion AgentCore.Application.State.ToolStateWriter AgentCore.Application.State.UnfilledSlotReminder +AgentCore.Application.State.VocabularyCache +AgentCore.Application.State.VocabularyCache.LastGoodAt(string! slot) -> System.DateTimeOffset? +AgentCore.Application.State.VocabularyCache.Replace(string! slot, System.Collections.Generic.IReadOnlyList! values, int maxValues, string? wildcardValue = null) -> void +AgentCore.Application.State.VocabularyCache.Snapshot() -> System.Collections.Generic.IReadOnlyDictionary! +AgentCore.Application.State.VocabularyCache.VocabularyCache(System.TimeProvider? timeProvider = null) -> void +AgentCore.Application.State.VocabularyException +AgentCore.Application.State.VocabularyException.Slot.get -> string! +AgentCore.Application.State.VocabularyException.VocabularyException() -> void +AgentCore.Application.State.VocabularyException.VocabularyException(string! message) -> void +AgentCore.Application.State.VocabularyException.VocabularyException(string! message, System.Exception? innerException) -> void +AgentCore.Application.State.VocabularyView +AgentCore.Application.State.VocabularyView.$() -> AgentCore.Application.State.VocabularyView! +AgentCore.Application.State.VocabularyView.Equals(AgentCore.Application.State.VocabularyView? other) -> bool +AgentCore.Application.State.VocabularyView.NormalisedToOriginal.get -> System.Collections.Generic.IReadOnlyDictionary! +AgentCore.Application.State.VocabularyView.NormalisedToOriginal.init -> void +AgentCore.Application.State.VocabularyView.Originals.get -> System.Collections.Generic.IReadOnlyList! +AgentCore.Application.State.VocabularyView.Originals.init -> void +AgentCore.Application.State.VocabularyView.VocabularyView() -> void AgentCore.Application.Tools.Binding.BindingToolSource AgentCore.Application.Tools.Binding.BindingToolSource.BindingToolSource(AgentCore.Application.Tools.Binding.ToolBindingRegistry! registry) -> void AgentCore.Application.Tools.Binding.BindingToolSource.ProvideAsync(AgentCore.Application.Tools.Registry.ToolSourceContext! context, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> @@ -1178,6 +1284,12 @@ AgentCore.Application.Transcript.SourceContent.SourceContent() -> void AgentCore.Application.Transcript.TranscriptJson abstract AgentCore.Application.Call.CallInput.$() -> AgentCore.Application.Call.CallInput! abstract AgentCore.Application.Tools.DeclaredTool.CallAsync(Microsoft.Extensions.AI.AIFunctionArguments! arguments, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.ValueTask +virtual AgentCore.Application.Call.CallInput.EqualityContract.get -> System.Type! +virtual AgentCore.Application.Call.CallInput.Equals(AgentCore.Application.Call.CallInput? other) -> bool +virtual AgentCore.Application.Call.CallInput.PrintMembers(System.Text.StringBuilder! builder) -> bool +virtual AgentCore.Application.Tools.Binding.ToolBinding.Invoke(System.Text.Json.Nodes.JsonObject! arguments, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.ValueTask +~override AgentCore.Application.Providers.VendorSeam.Equals(object obj) -> bool +~override AgentCore.Application.Providers.VendorSeam.ToString() -> string const AgentCore.Application.Audit.AuditSinkFactory.MemoryKind = "memory" -> string! const AgentCore.Application.Audit.QueuedAuditSink.DefaultBatchSize = 100 -> int const AgentCore.Application.Audit.QueuedAuditSink.DefaultCapacity = 10000 -> int @@ -1189,12 +1301,18 @@ const AgentCore.Application.Configuration.Compilation.AgentKnowledge.DefaultLimi const AgentCore.Application.Configuration.Compilation.AgentKnowledge.DefaultMode = AgentCore.Application.Configuration.Schema.KnowledgeMode.Prefetch -> AgentCore.Application.Configuration.Schema.KnowledgeMode const AgentCore.Application.Configuration.Compilation.AgentKnowledge.DefaultScoped = true -> bool const AgentCore.Application.Configuration.Parsing.ConfigurationError.RootPointer = "" -> string! +const AgentCore.Application.Configuration.Parsing.ScopeTemplate.KeyPlaceholder = "{key}" -> string! +const AgentCore.Application.Configuration.Parsing.ScopeTemplate.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." -> string! const AgentCore.Application.Configuration.Parsing.SecretReference.Prefix = "${secret:" -> string! const AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.DefaultFallbackReply = "I am sorry. I could not finish that. Please say it again." -> string! const AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.DefaultRefusalReply = "I am sorry. I cannot help with that request." -> string! const AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.SupportedApiVersion = "agentcore/v1" -> string! const AgentCore.Application.Configuration.Schema.AgentKnowledgeConfiguration.MaximumLimit = 20 -> int const AgentCore.Application.Configuration.Schema.EvaluationConfiguration.DefaultSampleRate = 0 -> double +const AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.DefaultMaxAsks = 2 -> int +const AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.DefaultMaxCandidates = 6 -> int +const AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.DefaultProbeDeadlineSeconds = 5 -> int +const AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.DefaultProbeWaitMarginSeconds = 1 -> int const AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.DefaultNamespace = "url" -> string! const AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.DefaultAnalyzer = "none" -> string! const AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.DefaultCitation = "source-locator" -> string! @@ -1202,6 +1320,9 @@ const AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration. const AgentCore.Application.Configuration.Schema.ReservedStateSlots.CallDurationSeconds = "callDurationSeconds" -> string! const AgentCore.Application.Configuration.Schema.ReservedStateSlots.Stage = "stage" -> string! const AgentCore.Application.Configuration.Schema.ReservedStateSlots.TurnIndex = "turnIndex" -> string! +const AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.DefaultLinker = "exact" -> string! +const AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.DefaultMaxValues = 2000 -> int +const AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.DefaultRefreshSeconds = 0 -> int const AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.DefaultExportIntervalMilliseconds = 60000 -> int const AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.DefaultServiceName = "agentcore" -> string! const AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.MinimumExportIntervalMilliseconds = 60000 -> int @@ -1239,197 +1360,6 @@ const AgentCore.Application.Tools.Builtin.BuiltinToolNames.Draw = "ui.draw" -> s const AgentCore.Application.Tools.ToolErrorResult.ErrorProperty = "error" -> string! const AgentCore.Application.Tools.ToolErrorResult.MessageProperty = "message" -> string! const AgentCore.Application.Tools.ToolErrorResult.ToolProperty = "tool" -> string! -override AgentCore.Application.Call.CallChannel.Equals(object? obj) -> bool -override AgentCore.Application.Call.CallChannel.GetHashCode() -> int -override AgentCore.Application.Call.CallChannel.ToString() -> string! -override AgentCore.Application.Call.CallChannelContext.Equals(object? obj) -> bool -override AgentCore.Application.Call.CallChannelContext.GetHashCode() -> int -override AgentCore.Application.Call.CallChannelContext.ToString() -> string! -override AgentCore.Application.Call.CallInput.Barge.$() -> AgentCore.Application.Call.CallInput.Barge! -override AgentCore.Application.Call.CallInput.Barge.Equals(object? obj) -> bool -override AgentCore.Application.Call.CallInput.Barge.GetHashCode() -> int -override AgentCore.Application.Call.CallInput.Barge.ToString() -> string! -override AgentCore.Application.Call.CallInput.Equals(object? obj) -> bool -override AgentCore.Application.Call.CallInput.GetHashCode() -> int -override AgentCore.Application.Call.CallInput.Keypress.$() -> AgentCore.Application.Call.CallInput.Keypress! -override AgentCore.Application.Call.CallInput.Keypress.Equals(object? obj) -> bool -override AgentCore.Application.Call.CallInput.Keypress.GetHashCode() -> int -override AgentCore.Application.Call.CallInput.Keypress.ToString() -> string! -override AgentCore.Application.Call.CallInput.ToString() -> string! -override AgentCore.Application.Call.CallInput.Utterance.$() -> AgentCore.Application.Call.CallInput.Utterance! -override AgentCore.Application.Call.CallInput.Utterance.Equals(object? obj) -> bool -override AgentCore.Application.Call.CallInput.Utterance.GetHashCode() -> int -override AgentCore.Application.Call.CallInput.Utterance.ToString() -> string! -override AgentCore.Application.Calls.CallPage.Equals(object? obj) -> bool -override AgentCore.Application.Calls.CallPage.GetHashCode() -> int -override AgentCore.Application.Calls.CallPage.ToString() -> string! -override AgentCore.Application.Calls.CallRecord.Equals(object? obj) -> bool -override AgentCore.Application.Calls.CallRecord.GetHashCode() -> int -override AgentCore.Application.Calls.CallRecord.ToString() -> string! -override AgentCore.Application.Calls.CallSessionState.Equals(object? obj) -> bool -override AgentCore.Application.Calls.CallSessionState.GetHashCode() -> int -override AgentCore.Application.Calls.CallSessionState.ToString() -> string! -override AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.GetHashCode() -> int -override AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.ToString() -> string! -override AgentCore.Application.Configuration.Parsing.ConfigurationError.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Parsing.ConfigurationError.GetHashCode() -> int -override AgentCore.Application.Configuration.Parsing.ConfigurationError.ToString() -> string! -override AgentCore.Application.Configuration.Parsing.SecretReference.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Parsing.SecretReference.GetHashCode() -> int -override AgentCore.Application.Configuration.Parsing.SecretReference.ToString() -> string! -override AgentCore.Application.Configuration.Parsing.SecretTemplate.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Parsing.SecretTemplate.GetHashCode() -> int -override AgentCore.Application.Configuration.Parsing.SecretTemplate.ToString() -> string! -override AgentCore.Application.Configuration.Schema.AgentConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.AgentConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.AgentConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.AgentDefaults.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.AgentDefaults.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.AgentDefaults.ToString() -> string! -override AgentCore.Application.Configuration.Schema.AgentKnowledgeConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.AgentKnowledgeConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.AgentKnowledgeConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.AgentsConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.AgentsConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.AgentsConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.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! -override AgentCore.Application.Configuration.Schema.EvaluationConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.EvaluationConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.EvaluationConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.ExtractorConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.ExtractorConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.ExtractorConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.GraphConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.GraphConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.GraphConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.GraphEdgeConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.GraphEdgeConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.GraphEdgeConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.GraphNodeConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.GraphNodeConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.GraphNodeConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.GuardReference.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.GuardReference.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.GuardReference.ToString() -> string! -override AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.McpAllowEntry.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.McpAllowEntry.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.McpAllowEntry.ToString() -> string! -override AgentCore.Application.Configuration.Schema.McpRetryConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.McpRetryConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.McpRetryConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.McpServerConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.McpServerConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.McpServerConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.ModelReference.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.ModelReference.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.ModelReference.ToString() -> string! -override AgentCore.Application.Configuration.Schema.PolicyConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.PolicyConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.PolicyConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.ProvidersConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.ProvidersConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.ProvidersConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.StageConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.StageConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.StageConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.StageTransition.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.StageTransition.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.StageTransition.ToString() -> string! -override AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.StateSlotConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.StateSlotConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.TitlerConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.TitlerConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.TitlerConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.ToolConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.ToolConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.ToolConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Schema.ToolResultReference.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.ToolResultReference.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.ToolResultReference.ToString() -> string! -override AgentCore.Application.Configuration.Schema.VendorProviderConfiguration.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Schema.VendorProviderConfiguration.GetHashCode() -> int -override AgentCore.Application.Configuration.Schema.VendorProviderConfiguration.ToString() -> string! -override AgentCore.Application.Configuration.Validation.ConfigurationValidationResult.Equals(object? obj) -> bool -override AgentCore.Application.Configuration.Validation.ConfigurationValidationResult.GetHashCode() -> int -override AgentCore.Application.Configuration.Validation.ConfigurationValidationResult.ToString() -> string! -override AgentCore.Application.Evaluation.EvaluationScore.Equals(object? obj) -> bool -override AgentCore.Application.Evaluation.EvaluationScore.GetHashCode() -> int -override AgentCore.Application.Evaluation.EvaluationScore.ToString() -> string! -override AgentCore.Application.Knowledge.KnowledgePoint.Equals(object? obj) -> bool -override AgentCore.Application.Knowledge.KnowledgePoint.GetHashCode() -> int -override AgentCore.Application.Knowledge.KnowledgePoint.ToString() -> string! -override AgentCore.Application.Providers.VendorSeam.GetHashCode() -> int -override AgentCore.Application.Runtime.AgentCoreAgent.Description.get -> string? -override AgentCore.Application.Runtime.AgentCoreAgent.Name.get -> string? -override AgentCore.Application.Runtime.CallEvent.Equals(object? obj) -> bool -override AgentCore.Application.Runtime.CallEvent.GetHashCode() -> int -override AgentCore.Application.Runtime.CallEvent.ToString() -> string! -override AgentCore.Application.Runtime.CallTurnOrigin.Equals(object? obj) -> bool -override AgentCore.Application.Runtime.CallTurnOrigin.GetHashCode() -> int -override AgentCore.Application.Runtime.CallTurnOrigin.ToString() -> string! -override AgentCore.Application.Secrets.ResolvedSecrets.ToString() -> string! -override AgentCore.Application.Secrets.SecretName.Equals(object? obj) -> bool -override AgentCore.Application.Secrets.SecretName.GetHashCode() -> int -override AgentCore.Application.Secrets.SecretName.ToString() -> string! -override AgentCore.Application.State.StateExtractionResult.Equals(object? obj) -> bool -override AgentCore.Application.State.StateExtractionResult.GetHashCode() -> int -override AgentCore.Application.State.StateExtractionResult.ToString() -> string! -override AgentCore.Application.Tools.Builtin.BuiltinToolPorts.Equals(object? obj) -> bool -override AgentCore.Application.Tools.Builtin.BuiltinToolPorts.GetHashCode() -> int -override AgentCore.Application.Tools.Builtin.BuiltinToolPorts.ToString() -> string! -override AgentCore.Application.Tools.DeclaredTool.Description.get -> string! -override AgentCore.Application.Tools.DeclaredTool.JsonSchema.get -> System.Text.Json.JsonElement -override AgentCore.Application.Tools.DeclaredTool.Name.get -> string! -override AgentCore.Application.Tools.Registry.ToolRegistration.Equals(object? obj) -> bool -override AgentCore.Application.Tools.Registry.ToolRegistration.GetHashCode() -> int -override AgentCore.Application.Tools.Registry.ToolRegistration.ToString() -> string! -override AgentCore.Application.Tools.Registry.ToolSourceContext.Equals(object? obj) -> bool -override AgentCore.Application.Tools.Registry.ToolSourceContext.GetHashCode() -> int -override AgentCore.Application.Tools.Registry.ToolSourceContext.ToString() -> string! -override AgentCore.Application.Transcript.CallMessage.Equals(object? obj) -> bool -override AgentCore.Application.Transcript.CallMessage.GetHashCode() -> int -override AgentCore.Application.Transcript.CallMessage.ToString() -> string! -override sealed AgentCore.Application.Call.CallInput.Barge.Equals(AgentCore.Application.Call.CallInput? other) -> bool -override sealed AgentCore.Application.Call.CallInput.Keypress.Equals(AgentCore.Application.Call.CallInput? other) -> bool -override sealed AgentCore.Application.Call.CallInput.Utterance.Equals(AgentCore.Application.Call.CallInput? other) -> bool -override sealed AgentCore.Application.Tools.DeclaredTool.InvokeCoreAsync(Microsoft.Extensions.AI.AIFunctionArguments! arguments, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.ValueTask static AgentCore.Application.Audit.AuditSinkFactory.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.Call.CallChannel.operator !=(AgentCore.Application.Call.CallChannel? left, AgentCore.Application.Call.CallChannel? right) -> bool static AgentCore.Application.Call.CallChannel.operator ==(AgentCore.Application.Call.CallChannel? left, AgentCore.Application.Call.CallChannel? right) -> bool @@ -1446,6 +1376,8 @@ static AgentCore.Application.Call.CallInput.operator ==(AgentCore.Application.Ca static AgentCore.Application.Call.CallSpeechPairing.Validate(AgentCore.Application.Configuration.Schema.CallProviderConfiguration! call, AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration! speech, AgentCore.Application.Ports.ICallAdapter! selectedCall) -> void static AgentCore.Application.Calls.CallCursor.Encode(System.DateTimeOffset sortAt, string! callId) -> string! static AgentCore.Application.Calls.CallCursor.TryDecode(string? cursor, out System.DateTimeOffset sortAt, out string! callId) -> bool +static AgentCore.Application.Calls.CallClarificationState.operator !=(AgentCore.Application.Calls.CallClarificationState? left, AgentCore.Application.Calls.CallClarificationState? right) -> bool +static AgentCore.Application.Calls.CallClarificationState.operator ==(AgentCore.Application.Calls.CallClarificationState? left, AgentCore.Application.Calls.CallClarificationState? right) -> bool static AgentCore.Application.Calls.CallPage.operator !=(AgentCore.Application.Calls.CallPage? left, AgentCore.Application.Calls.CallPage? right) -> bool static AgentCore.Application.Calls.CallPage.operator ==(AgentCore.Application.Calls.CallPage? left, AgentCore.Application.Calls.CallPage? right) -> bool static AgentCore.Application.Calls.CallRecord.operator !=(AgentCore.Application.Calls.CallRecord? left, AgentCore.Application.Calls.CallRecord? right) -> bool @@ -1461,6 +1393,9 @@ static AgentCore.Application.Configuration.Compilation.AgentKnowledge.AnyScoped( static AgentCore.Application.Configuration.Compilation.AgentKnowledge.Compose(AgentCore.Application.Configuration.Schema.AgentDefaults? defaults, AgentCore.Application.Configuration.Schema.AgentConfiguration! agent) -> AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? static AgentCore.Application.Configuration.Compilation.ConfigurationCompiler.Compile(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, AgentCore.Application.Configuration.Compilation.AgentCompilationContext! context) -> AgentCore.Application.Configuration.Compilation.CompiledAgent! static AgentCore.Application.Configuration.Compilation.ConfigurationCompiler.SelectShape(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration) -> AgentCore.Application.Configuration.Compilation.CompiledAgentShape +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.ResolvedKnowledge.operator !=(AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? left, AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? right) -> bool static AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.operator ==(AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? left, AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? right) -> bool static AgentCore.Application.Configuration.Parsing.ConfigurationError.AppendPointer(string! pointer, int index) -> string! @@ -1476,6 +1411,9 @@ static AgentCore.Application.Configuration.Parsing.ConfigurationLoader.ReadDocum static AgentCore.Application.Configuration.Parsing.ConfigurationSchemaValidator.Evaluate(System.Text.Json.Nodes.JsonNode! document) -> System.Collections.Generic.IReadOnlyList! static AgentCore.Application.Configuration.Parsing.ConfigurationSchemaValidator.SchemaJson.get -> string! static AgentCore.Application.Configuration.Parsing.ConfigurationSchemaValidator.Validate(System.Text.Json.Nodes.JsonNode! document) -> void +static AgentCore.Application.Configuration.Parsing.ScopeTemplate.Parse(string? text) -> AgentCore.Application.Configuration.Parsing.ScopeTemplate? +static AgentCore.Application.Configuration.Parsing.ScopeTemplate.operator !=(AgentCore.Application.Configuration.Parsing.ScopeTemplate? left, AgentCore.Application.Configuration.Parsing.ScopeTemplate? right) -> bool +static AgentCore.Application.Configuration.Parsing.ScopeTemplate.operator ==(AgentCore.Application.Configuration.Parsing.ScopeTemplate? left, AgentCore.Application.Configuration.Parsing.ScopeTemplate? right) -> bool static AgentCore.Application.Configuration.Parsing.SecretReference.operator !=(AgentCore.Application.Configuration.Parsing.SecretReference? left, AgentCore.Application.Configuration.Parsing.SecretReference? right) -> bool static AgentCore.Application.Configuration.Parsing.SecretReference.operator ==(AgentCore.Application.Configuration.Parsing.SecretReference? left, AgentCore.Application.Configuration.Parsing.SecretReference? right) -> bool static AgentCore.Application.Configuration.Parsing.SecretTemplate.Parse(string! text) -> AgentCore.Application.Configuration.Parsing.SecretTemplate! @@ -1512,6 +1450,8 @@ static AgentCore.Application.Configuration.Schema.GuardReference.operator !=(Age static AgentCore.Application.Configuration.Schema.GuardReference.operator ==(AgentCore.Application.Configuration.Schema.GuardReference? left, AgentCore.Application.Configuration.Schema.GuardReference? right) -> bool static AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.operator !=(AgentCore.Application.Configuration.Schema.HttpRequestConfiguration? left, AgentCore.Application.Configuration.Schema.HttpRequestConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.operator ==(AgentCore.Application.Configuration.Schema.HttpRequestConfiguration? left, AgentCore.Application.Configuration.Schema.HttpRequestConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration? right) -> bool @@ -1538,6 +1478,8 @@ static AgentCore.Application.Configuration.Schema.ProvidersConfiguration.operato static AgentCore.Application.Configuration.Schema.ProvidersConfiguration.operator ==(AgentCore.Application.Configuration.Schema.ProvidersConfiguration? left, AgentCore.Application.Configuration.Schema.ProvidersConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.ReservedStateSlots.All.get -> System.Collections.Generic.IReadOnlyList! static AgentCore.Application.Configuration.Schema.ReservedStateSlots.Contains(string! name) -> bool +static AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.operator !=(AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration? left, AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.operator ==(AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration? left, AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.operator !=(AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration? left, AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.operator ==(AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration? left, AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.StageConfiguration.operator !=(AgentCore.Application.Configuration.Schema.StageConfiguration? left, AgentCore.Application.Configuration.Schema.StageConfiguration? right) -> bool @@ -1563,6 +1505,7 @@ static AgentCore.Application.Configuration.Validation.ConfigurationValidationRes static AgentCore.Application.Configuration.Validation.ConfigurationValidator.Evaluate(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration) -> AgentCore.Application.Configuration.Validation.ConfigurationValidationResult! static AgentCore.Application.Configuration.Validation.ConfigurationValidator.EvaluateStructure(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration) -> AgentCore.Application.Configuration.Validation.ConfigurationValidationResult! static AgentCore.Application.Configuration.Validation.ConfigurationValidator.Validate(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration) -> AgentCore.Application.Configuration.Validation.ConfigurationValidationResult! +static AgentCore.Application.Configuration.Validation.ConfigurationValidator.ValidateLinkerNames(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, System.Collections.Generic.IReadOnlySet! registered) -> void static AgentCore.Application.Configuration.Validation.ConfigurationValidator.ValidateSkillReferences(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, System.Collections.Generic.IReadOnlySet! servedSkillNames) -> void static AgentCore.Application.Configuration.Validation.ConfigurationValidator.ValidateSkillToolNames(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration) -> void static AgentCore.Application.Configuration.Validation.ConfigurationValidator.ValidateStructure(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration) -> AgentCore.Application.Configuration.Validation.ConfigurationValidationResult! @@ -1596,6 +1539,7 @@ static AgentCore.Application.Runtime.CallEvent.operator ==(AgentCore.Application static AgentCore.Application.Runtime.CallObservers.Standard(AgentCore.Application.Ports.IAuditSinkPort! auditSink, Microsoft.Extensions.Logging.ILogger? logger, System.Collections.Generic.IEnumerable? hostObservers = null) -> System.Collections.Generic.IReadOnlyList! static AgentCore.Application.Runtime.CallRenderScope.Current.get -> AgentCore.Application.Ports.IRenderPort? static AgentCore.Application.Runtime.CallSessionFactory.CreateExtractor(AgentCore.Application.Configuration.Compilation.CompiledAgent! compiled, AgentCore.Application.Ports.IChatClientFactory! chatClients) -> AgentCore.Application.State.StateExtractor? +static AgentCore.Application.Runtime.CallSessionFactory.CreateExtractor(AgentCore.Application.Configuration.Compilation.CompiledAgent! compiled, AgentCore.Application.Ports.IChatClientFactory! chatClients, System.Collections.Generic.IEnumerable? linkers) -> AgentCore.Application.State.StateExtractor? static AgentCore.Application.Runtime.CallSourceScope.Current.get -> AgentCore.Application.Ports.ISourcePort? static AgentCore.Application.Runtime.CallStateScope.Enter(AgentCore.Application.State.StateDocument! state) -> System.IDisposable! static AgentCore.Application.Runtime.CallStateScope.Snapshot() -> System.Collections.Generic.IReadOnlyDictionary! @@ -1612,6 +1556,8 @@ static AgentCore.Application.Secrets.SecretResolutionException.Unresolved(string static AgentCore.Application.Secrets.SecretResolverExtensions.RequireAsync(this AgentCore.Application.Ports.ISecretResolverPort? secrets, AgentCore.Application.Secrets.SecretName! secret, string? because = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask static AgentCore.Application.Secrets.SecretResolverExtensions.TryReadAsync(this AgentCore.Application.Ports.ISecretResolverPort? secrets, AgentCore.Application.Secrets.SecretName! secret, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask static AgentCore.Application.State.ConstStateWriter.Apply(AgentCore.Application.State.StateDocument! state) -> int +static AgentCore.Application.State.LinkResult.operator !=(AgentCore.Application.State.LinkResult? left, AgentCore.Application.State.LinkResult? right) -> bool +static AgentCore.Application.State.LinkResult.operator ==(AgentCore.Application.State.LinkResult? left, AgentCore.Application.State.LinkResult? right) -> bool static AgentCore.Application.State.StateExtractionResult.Failed(string! failure) -> AgentCore.Application.State.StateExtractionResult! static AgentCore.Application.State.StateExtractionResult.operator !=(AgentCore.Application.State.StateExtractionResult? left, AgentCore.Application.State.StateExtractionResult? right) -> bool static AgentCore.Application.State.StateExtractionResult.operator ==(AgentCore.Application.State.StateExtractionResult? left, AgentCore.Application.State.StateExtractionResult? right) -> bool @@ -1621,6 +1567,12 @@ static AgentCore.Application.State.ToolStateWriter.Apply(AgentCore.Application.S static AgentCore.Application.State.UnfilledSlotReminder.Build(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, System.Collections.Generic.IReadOnlyList! slots) -> string? static AgentCore.Application.State.UnfilledSlotReminder.Build(AgentCore.Application.State.StateDocument! state, AgentCore.Application.Configuration.Schema.StageConfiguration! stage) -> string? static AgentCore.Application.State.UnfilledSlotReminder.UnfilledSlots(AgentCore.Application.State.StateDocument! state, AgentCore.Application.Configuration.Schema.StageConfiguration! stage) -> System.Collections.Generic.IReadOnlyList! +static AgentCore.Application.State.VocabularyException.FoldingCollision(string! slot, string! first, string! second, string! normalised) -> AgentCore.Application.State.VocabularyException! +static AgentCore.Application.State.VocabularyException.FoldsToEmpty(string! slot, string! value) -> AgentCore.Application.State.VocabularyException! +static AgentCore.Application.State.VocabularyException.NoValues(string! slot) -> AgentCore.Application.State.VocabularyException! +static AgentCore.Application.State.VocabularyException.Truncated(string! slot, int maxValues) -> AgentCore.Application.State.VocabularyException! +static AgentCore.Application.State.VocabularyView.operator !=(AgentCore.Application.State.VocabularyView? left, AgentCore.Application.State.VocabularyView? right) -> bool +static AgentCore.Application.State.VocabularyView.operator ==(AgentCore.Application.State.VocabularyView? left, AgentCore.Application.State.VocabularyView? right) -> bool static AgentCore.Application.Tools.Builtin.BuiltinToolPorts.operator !=(AgentCore.Application.Tools.Builtin.BuiltinToolPorts? left, AgentCore.Application.Tools.Builtin.BuiltinToolPorts? right) -> bool static AgentCore.Application.Tools.Builtin.BuiltinToolPorts.operator ==(AgentCore.Application.Tools.Builtin.BuiltinToolPorts? left, AgentCore.Application.Tools.Builtin.BuiltinToolPorts? right) -> bool static AgentCore.Application.Tools.DeclaredTool.ArgumentText(Microsoft.Extensions.AI.AIFunctionArguments! arguments, string! name) -> string? @@ -1638,6 +1590,7 @@ static AgentCore.Application.Tools.ToolResultJson.ToNode(object? value) -> Syste static AgentCore.Application.Transcript.CallMessage.operator !=(AgentCore.Application.Transcript.CallMessage? left, AgentCore.Application.Transcript.CallMessage? right) -> bool static AgentCore.Application.Transcript.CallMessage.operator ==(AgentCore.Application.Transcript.CallMessage? left, AgentCore.Application.Transcript.CallMessage? right) -> bool static AgentCore.Application.Transcript.TranscriptJson.Options.get -> System.Text.Json.JsonSerializerOptions! +static readonly AgentCore.Application.Configuration.Compilation.ResolvedClarification.None -> AgentCore.Application.Configuration.Compilation.ResolvedClarification! static readonly AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.DefaultMeters -> System.Collections.Generic.IReadOnlyList! static readonly AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.DefaultSources -> System.Collections.Generic.IReadOnlyList! static readonly AgentCore.Application.Secrets.KnownSecrets.GrafanaCloudApiToken -> AgentCore.Application.Secrets.SecretName! @@ -1646,9 +1599,215 @@ static readonly AgentCore.Application.Secrets.KnownSecrets.OpenAi -> AgentCore.A static readonly AgentCore.Application.Secrets.KnownSecrets.PostgresConnectionString -> AgentCore.Application.Secrets.SecretName! static readonly AgentCore.Application.Secrets.KnownSecrets.Qdrant -> AgentCore.Application.Secrets.SecretName! static readonly AgentCore.Application.Sessions.Memory.InMemoryCallSessions.DefaultIdleTimeout -> System.TimeSpan -virtual AgentCore.Application.Call.CallInput.EqualityContract.get -> System.Type! -virtual AgentCore.Application.Call.CallInput.Equals(AgentCore.Application.Call.CallInput? other) -> bool -virtual AgentCore.Application.Call.CallInput.PrintMembers(System.Text.StringBuilder! builder) -> bool -virtual AgentCore.Application.Tools.Binding.ToolBinding.Invoke(System.Text.Json.Nodes.JsonObject! arguments, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.ValueTask -~override AgentCore.Application.Providers.VendorSeam.Equals(object obj) -> bool -~override AgentCore.Application.Providers.VendorSeam.ToString() -> string +override AgentCore.Application.Call.CallChannel.Equals(object? obj) -> bool +override AgentCore.Application.Call.CallChannel.GetHashCode() -> int +override AgentCore.Application.Call.CallChannel.ToString() -> string! +override AgentCore.Application.Call.CallChannelContext.Equals(object? obj) -> bool +override AgentCore.Application.Call.CallChannelContext.GetHashCode() -> int +override AgentCore.Application.Call.CallChannelContext.ToString() -> string! +override AgentCore.Application.Call.CallInput.Barge.$() -> AgentCore.Application.Call.CallInput.Barge! +override AgentCore.Application.Call.CallInput.Barge.Equals(object? obj) -> bool +override AgentCore.Application.Call.CallInput.Barge.GetHashCode() -> int +override AgentCore.Application.Call.CallInput.Barge.ToString() -> string! +override AgentCore.Application.Call.CallInput.Equals(object? obj) -> bool +override AgentCore.Application.Call.CallInput.GetHashCode() -> int +override AgentCore.Application.Call.CallInput.Keypress.$() -> AgentCore.Application.Call.CallInput.Keypress! +override AgentCore.Application.Call.CallInput.Keypress.Equals(object? obj) -> bool +override AgentCore.Application.Call.CallInput.Keypress.GetHashCode() -> int +override AgentCore.Application.Call.CallInput.Keypress.ToString() -> string! +override AgentCore.Application.Call.CallInput.ToString() -> string! +override AgentCore.Application.Call.CallInput.Utterance.$() -> AgentCore.Application.Call.CallInput.Utterance! +override AgentCore.Application.Call.CallInput.Utterance.Equals(object? obj) -> bool +override AgentCore.Application.Call.CallInput.Utterance.GetHashCode() -> int +override AgentCore.Application.Call.CallInput.Utterance.ToString() -> string! +override AgentCore.Application.Calls.CallClarificationState.Equals(object? obj) -> bool +override AgentCore.Application.Calls.CallClarificationState.GetHashCode() -> int +override AgentCore.Application.Calls.CallClarificationState.ToString() -> string! +override AgentCore.Application.Calls.CallPage.Equals(object? obj) -> bool +override AgentCore.Application.Calls.CallPage.GetHashCode() -> int +override AgentCore.Application.Calls.CallPage.ToString() -> string! +override AgentCore.Application.Calls.CallRecord.Equals(object? obj) -> bool +override AgentCore.Application.Calls.CallRecord.GetHashCode() -> int +override AgentCore.Application.Calls.CallRecord.ToString() -> string! +override AgentCore.Application.Calls.CallSessionState.Equals(object? obj) -> bool +override AgentCore.Application.Calls.CallSessionState.GetHashCode() -> int +override AgentCore.Application.Calls.CallSessionState.ToString() -> string! +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.ResolvedKnowledge.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.GetHashCode() -> int +override AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.ToString() -> string! +override AgentCore.Application.Configuration.Parsing.ConfigurationError.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Parsing.ConfigurationError.GetHashCode() -> int +override AgentCore.Application.Configuration.Parsing.ConfigurationError.ToString() -> string! +override AgentCore.Application.Configuration.Parsing.ScopeTemplate.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Parsing.ScopeTemplate.GetHashCode() -> int +override AgentCore.Application.Configuration.Parsing.ScopeTemplate.ToString() -> string! +override AgentCore.Application.Configuration.Parsing.SecretReference.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Parsing.SecretReference.GetHashCode() -> int +override AgentCore.Application.Configuration.Parsing.SecretReference.ToString() -> string! +override AgentCore.Application.Configuration.Parsing.SecretTemplate.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Parsing.SecretTemplate.GetHashCode() -> int +override AgentCore.Application.Configuration.Parsing.SecretTemplate.ToString() -> string! +override AgentCore.Application.Configuration.Schema.AgentConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.AgentConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.AgentConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.AgentDefaults.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.AgentDefaults.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.AgentDefaults.ToString() -> string! +override AgentCore.Application.Configuration.Schema.AgentKnowledgeConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.AgentKnowledgeConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.AgentKnowledgeConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.AgentsConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.AgentsConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.AgentsConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.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! +override AgentCore.Application.Configuration.Schema.EvaluationConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.EvaluationConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.EvaluationConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.ExtractorConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.ExtractorConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.ExtractorConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.GraphConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.GraphConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.GraphConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.GraphEdgeConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.GraphEdgeConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.GraphEdgeConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.GraphNodeConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.GraphNodeConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.GraphNodeConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.GuardReference.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.GuardReference.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.GuardReference.ToString() -> string! +override AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeLinksConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeProviderConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeScopeConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeWildcardConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.McpAllowEntry.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.McpAllowEntry.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.McpAllowEntry.ToString() -> string! +override AgentCore.Application.Configuration.Schema.McpRetryConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.McpRetryConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.McpRetryConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.McpServerConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.McpServerConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.McpServerConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.ModelReference.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.ModelReference.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.ModelReference.ToString() -> string! +override AgentCore.Application.Configuration.Schema.PolicyConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.PolicyConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.PolicyConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.ProvidersConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.ProvidersConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.ProvidersConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.SlotVocabularyConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.SpeechProviderConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.StageConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.StageConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.StageConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.StageTransition.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.StageTransition.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.StageTransition.ToString() -> string! +override AgentCore.Application.Configuration.Schema.StateSlotConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.StateSlotConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.StateSlotConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.TelemetryProviderConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.TitlerConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.TitlerConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.TitlerConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.ToolConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.ToolConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.ToolConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.ToolResultReference.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.ToolResultReference.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.ToolResultReference.ToString() -> string! +override AgentCore.Application.Configuration.Schema.VendorProviderConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.VendorProviderConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.VendorProviderConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Validation.ConfigurationValidationResult.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Validation.ConfigurationValidationResult.GetHashCode() -> int +override AgentCore.Application.Configuration.Validation.ConfigurationValidationResult.ToString() -> string! +override AgentCore.Application.Evaluation.EvaluationScore.Equals(object? obj) -> bool +override AgentCore.Application.Evaluation.EvaluationScore.GetHashCode() -> int +override AgentCore.Application.Evaluation.EvaluationScore.ToString() -> string! +override AgentCore.Application.Knowledge.KnowledgePoint.Equals(object? obj) -> bool +override AgentCore.Application.Knowledge.KnowledgePoint.GetHashCode() -> int +override AgentCore.Application.Knowledge.KnowledgePoint.ToString() -> string! +override AgentCore.Application.Providers.VendorSeam.GetHashCode() -> int +override AgentCore.Application.Runtime.AgentCoreAgent.Description.get -> string? +override AgentCore.Application.Runtime.AgentCoreAgent.Name.get -> string? +override AgentCore.Application.Runtime.CallEvent.Equals(object? obj) -> bool +override AgentCore.Application.Runtime.CallEvent.GetHashCode() -> int +override AgentCore.Application.Runtime.CallEvent.ToString() -> string! +override AgentCore.Application.Runtime.CallTurnOrigin.Equals(object? obj) -> bool +override AgentCore.Application.Runtime.CallTurnOrigin.GetHashCode() -> int +override AgentCore.Application.Runtime.CallTurnOrigin.ToString() -> string! +override AgentCore.Application.Secrets.ResolvedSecrets.ToString() -> string! +override AgentCore.Application.Secrets.SecretName.Equals(object? obj) -> bool +override AgentCore.Application.Secrets.SecretName.GetHashCode() -> int +override AgentCore.Application.Secrets.SecretName.ToString() -> string! +override AgentCore.Application.State.LinkResult.Equals(object? obj) -> bool +override AgentCore.Application.State.LinkResult.GetHashCode() -> int +override AgentCore.Application.State.LinkResult.ToString() -> string! +override AgentCore.Application.State.StateExtractionResult.Equals(object? obj) -> bool +override AgentCore.Application.State.StateExtractionResult.GetHashCode() -> int +override AgentCore.Application.State.StateExtractionResult.ToString() -> string! +override AgentCore.Application.State.VocabularyView.Equals(object? obj) -> bool +override AgentCore.Application.State.VocabularyView.GetHashCode() -> int +override AgentCore.Application.State.VocabularyView.ToString() -> string! +override AgentCore.Application.Tools.Builtin.BuiltinToolPorts.Equals(object? obj) -> bool +override AgentCore.Application.Tools.Builtin.BuiltinToolPorts.GetHashCode() -> int +override AgentCore.Application.Tools.Builtin.BuiltinToolPorts.ToString() -> string! +override AgentCore.Application.Tools.DeclaredTool.Description.get -> string! +override AgentCore.Application.Tools.DeclaredTool.JsonSchema.get -> System.Text.Json.JsonElement +override AgentCore.Application.Tools.DeclaredTool.Name.get -> string! +override AgentCore.Application.Tools.Registry.ToolRegistration.Equals(object? obj) -> bool +override AgentCore.Application.Tools.Registry.ToolRegistration.GetHashCode() -> int +override AgentCore.Application.Tools.Registry.ToolRegistration.ToString() -> string! +override AgentCore.Application.Tools.Registry.ToolSourceContext.Equals(object? obj) -> bool +override AgentCore.Application.Tools.Registry.ToolSourceContext.GetHashCode() -> int +override AgentCore.Application.Tools.Registry.ToolSourceContext.ToString() -> string! +override AgentCore.Application.Transcript.CallMessage.Equals(object? obj) -> bool +override AgentCore.Application.Transcript.CallMessage.GetHashCode() -> int +override AgentCore.Application.Transcript.CallMessage.ToString() -> string! +override sealed AgentCore.Application.Call.CallInput.Barge.Equals(AgentCore.Application.Call.CallInput? other) -> bool +override sealed AgentCore.Application.Call.CallInput.Keypress.Equals(AgentCore.Application.Call.CallInput? other) -> bool +override sealed AgentCore.Application.Call.CallInput.Utterance.Equals(AgentCore.Application.Call.CallInput? other) -> bool +override sealed AgentCore.Application.Tools.DeclaredTool.InvokeCoreAsync(Microsoft.Extensions.AI.AIFunctionArguments! arguments, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.ValueTask diff --git a/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs b/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs index 6af0845e..42732c08 100644 --- a/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs +++ b/src/AgentCore.Application/Runtime/AuditingFunctionInvokingChatClient.cs @@ -30,7 +30,15 @@ internal AuditingFunctionInvokingChatClient(IChatClient innerClient) { ArgumentNullException.ThrowIfNull(context); - using var outerCall = OuterToolCall.Enter(context.CallContent.CallId); + using var outerCall = OuterToolCall.Enter(context.CallContent.CallId, out var nested); + + // A delegated run must not touch the caller's Clarifications: it would burn the turn's probe + // and record a lastNamed from a note the caller never heard (K42). The knowledge search + // itself is a tool call, so the strip is conditional on being nested rather than unconditional + // — an unconditional strip would blind the caller's own search too. + using IDisposable? strippedClarifications = nested + ? TurnAmbients.Amend(ambients => ambients with { Clarifications = null }) + : null; try { diff --git a/src/AgentCore.Application/Runtime/CallSession.cs b/src/AgentCore.Application/Runtime/CallSession.cs index 0d5aced2..364fd4e5 100644 --- a/src/AgentCore.Application/Runtime/CallSession.cs +++ b/src/AgentCore.Application/Runtime/CallSession.cs @@ -96,6 +96,10 @@ public sealed class CallSession : IConversationPort private CallSessionState? _checkpoint; + private readonly Clarifications _clarifications = new(); + + private readonly IReadOnlyDictionary _vocabulary; + // 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, // so a barge-in in that window belongs to the turn that finished before it. A streaming turn @@ -120,7 +124,8 @@ internal CallSession( StateExtractor? extractor, TimeProvider timeProvider, CallObserverDispatcher? observers = null, - ILogger? logger = null) + ILogger? logger = null, + VocabularyCache? vocabulary = null) { ArgumentException.ThrowIfNullOrEmpty(callId); ArgumentNullException.ThrowIfNull(compiled); @@ -153,7 +158,11 @@ internal CallSession( // read that way, and neither of them ever ends a call by itself. _policy = compiled.Configuration.Policy is null ? null : compiled.CreatePolicy(guards); - State = new StateDocument(compiled.Configuration, _policy?.Stage); + // Sampled once, here, and handed to both the gate and the linker (K40): a refresh landing + // mid-call must not let the two sides of one write disagree about what the vocabulary was. + _vocabulary = vocabulary?.Snapshot() ?? new Dictionary(StringComparer.Ordinal); + + State = new StateDocument(compiled.Configuration, _policy?.Stage, _vocabulary); // 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 @@ -563,6 +572,8 @@ internal CallSessionState Snapshot() // commit path the provider overwrites it, because the ordinal this turn leaves behind is // not settled until the turn's rows are cut. NextOrdinal = Session() is { } session ? _history.NextOrdinal(session) : 0, + + Clarifications = _clarifications.Spent(), }; } @@ -634,6 +645,11 @@ private void Restore(CallSessionState stored) Dropped(refusedStage); } + // Before the slots, and unconditionally: the ask budget is per call, 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. + _clarifications.RestoreSpent(stored.Clarifications); + foreach (var slot in stored.Slots) { if (ReservedStateSlots.Contains(slot.Key)) @@ -652,8 +668,10 @@ private void Restore(CallSessionState stored) continue; } - // TryWrite answers false for exactly two things, and they cost an operator different - // things to fix, so the reason says which one happened rather than making them guess. + // 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, enum: or + // vocabulary: gate now refuses — so the reason says which one happened rather than + // making them guess. Dropped( State.Configuration.State.ContainsKey(slot.Key) ? $"the slot '{slot.Key}' no longer takes the value it was stored with." @@ -693,7 +711,8 @@ private IDisposable EnterAmbients(Turn turn) turn.Sources, failure => _events.RaiseToolFailure(turn.Index, failure), TurnContextOf(turn), - turn.Knowledge); + turn.Knowledge, + _clarifications); /// /// Reads what one turn adds to its own model invocation. @@ -707,6 +726,7 @@ private TurnContext TurnContextOf(Turn turn) Instructions = turn.Reminder, Tools = _delegatedTools?.Tools, ToolsFor = _delegatedTools?.ToolId, + CarriesHistory = _sessionCarriesHistory, }; /// @@ -759,59 +779,78 @@ private Turn BeginTurn(string userInput, AgentSession session, CallTurnOrigin? o $"A turn of the call '{CallId}' is still running. One call runs one turn at a time."); } - // Behind both guards, because the withdrawal deletes: a turn refused for a terminal call or - // for one already running must not have taken the tail of the call 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 a document with a policy: has a stage that waits on a slot. - var reminder = _policy is null ? null : UnfilledSlotReminder.Build(State, _policy.CurrentStage); - ChatMessage spoken = new(ChatRole.User, userInput); - - // The framework has never heard of a turn, so the turn loop names this one before the run. - _history.BeginTurn(session, State.TurnIndex); - - // Rows 1 and 2 read the call out of the session, so the run carries the new message alone - // and the provider prepends the rest. A workflow 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 = _sessionCarriesHistory - ? [spoken] - : TurnMessages.GraphHistory(_history.Read(session)) is { } rendered ? [rendered, spoken] : [spoken]; - - // One turn is one span. The call 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. - var activity = AgentCoreTelemetry.StartTurn(CallId, State.TurnIndex, State.Stage); - - var knowledge = StateKnowledgeScope.Compose( - State, _compiled.Configuration.Providers?.Knowledge?.Scope, KnowledgeScopeScope.Current); - - if (knowledge is { Origins.Count: > 0 }) + Activity? activity = null; + try { - Log.KnowledgeScopeComposed(_logger, CallId, State.TurnIndex, knowledge.Origins); - } + // After both guards: a turn refused as terminal or already-running must not clear the + // per-turn mark out from under the turn actually in flight. Runs exactly once here, and + // never in EnterAmbients, which reopens per streaming step and would clear the mark + // several times inside one streaming turn (K41). + _clarifications.BeginTurn(); + + // Behind both guards, because the withdrawal deletes: a turn refused for a terminal call or + // for one already running must not have taken the tail of the call 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 a document with a policy: has a stage that waits on a slot. + var reminder = _policy is null ? null : UnfilledSlotReminder.Build(State, _policy.CurrentStage); + ChatMessage spoken = new(ChatRole.User, userInput); + + // The framework has never heard of a turn, so the turn loop names this one before the run. + _history.BeginTurn(session, State.TurnIndex); + + // Rows 1 and 2 read the call out of the session, so the run carries the new message alone + // and the provider prepends the rest. A workflow 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 = _sessionCarriesHistory + ? [spoken] + : TurnMessages.GraphHistory(_history.Read(session)) is { } rendered ? [rendered, spoken] : [spoken]; + + // One turn is one span. The call 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(CallId, State.TurnIndex, State.Stage); + + var knowledge = StateKnowledgeScope.Compose( + State, _compiled.Configuration.Providers?.Knowledge?.Scope, KnowledgeScopeScope.Current); + + if (knowledge is { Origins.Count: > 0 }) + { + Log.KnowledgeScopeComposed(_logger, CallId, State.TurnIndex, knowledge.Origins); + } - return new Turn( - agent, - session, - request, - spoken, - reminder, - State.Stage, - State.TurnIndex, - activity, - _time.GetTimestamp(), - _hasScreen ? new TurnRenders() : null, - new TurnSources(), - knowledge, - origin?.MessageId); + return new Turn( + agent, + session, + request, + spoken, + reminder, + State.Stage, + State.TurnIndex, + activity, + _time.GetTimestamp(), + _hasScreen ? new TurnRenders() : null, + new TurnSources(), + knowledge, + origin?.MessageId); + } + 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 call is refused as one already running. + activity?.Dispose(); + Volatile.Write(ref _running, 0); + throw; + } } /// Takes back everything the call said after the message this turn hangs off. @@ -823,6 +862,13 @@ private void WithdrawSuperseded(AgentSession session, CallTurnOrigin? origin) return; } + // Without this, lastNamed and the pending list would survive a withdrawal that deleted the + // very turns they recorded, and silence both ambiguity channels forever about a question the + // caller edited away. The ask counters are deliberately untouched here: what the caller + // heard, they still heard, and clearing them would let the withdrawn segment buy a fresh + // maxAsks budget. + _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. @@ -1009,6 +1055,15 @@ private async Task CompleteTurnAsync( _events.RaiseDiagnostic(CallEventKind.EmptyReply, _time.GetUtcNow(), turn.Index); } + // §7's ask is charged only for a turn whose own words reached the caller. The clarification + // rides an instruction injected before the run, so a run that ended in the fallback reply, or + // one moderation refused, never put the question — and a slot recorded as asked is silent for + // the rest of the call. + if (failure is null && !refused) + { + _clarifications.CommitAsks(); + } + // What this turn adds to the transcript. It is built here and written at the end of the // method, 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 between here @@ -1266,7 +1321,8 @@ private async Task CompleteTurnAsync( } // A failed extraction never drops the turn. The result carries the reason instead. - var result = await _extractor.ExtractAsync(State, finished, cancellationToken).ConfigureAwait(false); + var result = await _extractor.ExtractAsync(State, finished, _clarifications, cancellationToken) + .ConfigureAwait(false); return result.Failure; } diff --git a/src/AgentCore.Application/Runtime/CallSessionFactory.cs b/src/AgentCore.Application/Runtime/CallSessionFactory.cs index 6389a42d..45ee76fe 100644 --- a/src/AgentCore.Application/Runtime/CallSessionFactory.cs +++ b/src/AgentCore.Application/Runtime/CallSessionFactory.cs @@ -22,9 +22,11 @@ public sealed class CallSessionFactory : ICallSessionFactory private readonly TimeProvider _time; private readonly ICallObserver[] _observers; - + private readonly ILogger? _logger; + private readonly VocabularyCache? _vocabulary; + /// Creates the factory. public CallSessionFactory( CompiledAgent compiled, @@ -32,7 +34,8 @@ public CallSessionFactory( StateExtractor? extractor = null, TimeProvider? timeProvider = null, ILogger? logger = null, - IEnumerable? observers = null) + IEnumerable? observers = null, + VocabularyCache? vocabulary = null) { ArgumentNullException.ThrowIfNull(compiled); ArgumentNullException.ThrowIfNull(guards); @@ -42,6 +45,7 @@ public CallSessionFactory( _extractor = extractor; _time = timeProvider ?? TimeProvider.System; _logger = logger; + _vocabulary = vocabulary; // 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 @@ -54,9 +58,34 @@ public CallSessionFactory( /// The seam that resolves extractor.model. /// The extractor, or when the document declares none. public static StateExtractor? CreateExtractor(CompiledAgent compiled, IChatClientFactory chatClients) + => CreateExtractor(compiled, chatClients, new StateValueLinkers([])); + + /// Builds the extractor one document declares, over the linkers a host bound with UseStateValueLinkers. + /// The compiled agent. + /// The seam that resolves extractor.model. + /// + /// The linkers to resolve each vocabulary: slot's vocabulary.linker name against, + /// beyond the built-in exact, or for none. StateValueLinkers, + /// the registry type this builds, is to this assembly — this overload + /// is the public seam a host-facing project such as AspNetCore reaches it through, mirroring how + /// 's own constructor already takes the vocabulary cache by its + /// public type rather than an internal one. + /// + /// The extractor, or when the document declares none. + public static StateExtractor? CreateExtractor( + CompiledAgent compiled, IChatClientFactory chatClients, IEnumerable? linkers) + => CreateExtractor(compiled, chatClients, new StateValueLinkers(linkers ?? [])); + + /// Builds the extractor one document declares, over a vocabulary.linker registry (K12). + /// The compiled agent. + /// The seam that resolves extractor.model. + /// The registry the extractor resolves each vocabulary: slot's linker against. + /// The extractor, or when the document declares none. + internal static StateExtractor? CreateExtractor(CompiledAgent compiled, IChatClientFactory chatClients, StateValueLinkers linkers) { ArgumentNullException.ThrowIfNull(compiled); ArgumentNullException.ThrowIfNull(chatClients); + ArgumentNullException.ThrowIfNull(linkers); return compiled.Configuration.Extractor is { } declared ? new StateExtractor( @@ -65,7 +94,8 @@ public CallSessionFactory( .AsBuilder() .UseOpenTelemetry(configure: static client => client.EnableSensitiveData = false) .Use(static innerClient => new ModelFacingChatClient(innerClient)) - .Build()) + .Build(), + linkers) : null; } @@ -79,7 +109,8 @@ public CallSession Create(string? callId = null, CallSessionState? state = null) _extractor, _time, new CallObserverDispatcher(_observers, _logger), - _logger); + _logger, + _vocabulary); // Named, not applied. The session resumes on its first turn, where store 0's own copy // outranks this one — see the remarks on CallSession.Resume. diff --git a/src/AgentCore.Application/Runtime/ClarificationProvider.cs b/src/AgentCore.Application/Runtime/ClarificationProvider.cs new file mode 100644 index 00000000..305773a7 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ClarificationProvider.cs @@ -0,0 +1,134 @@ +using AgentCore.Application.Configuration.Schema; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime; + +/// +/// Channel 1 of the ambiguity design (§7): the clarification, riding as a turn instruction. Bound +/// beside on every compiled agent whose document declares +/// providers.knowledge.ambiguity. +/// +/// +/// Uses the same session guard as : when +/// returns for the run's own session, this +/// is not the caller's own turn — a delegated kind: agent run, or a participant of a +/// graph: row whose session never carries the call's own history — and the channel emits +/// nothing and counts nothing (K29, K39). Because s run once per +/// RunAsync, above the framework's tool-call loop, this also means a nested tool call never +/// reaches this type at all; the K42 strip that hides from a nested +/// search exists for the probe, not for this provider. +/// +internal sealed class ClarificationProvider : AIContextProvider +{ + private readonly KnowledgeAmbiguityConfiguration _ambiguity; + + private readonly IReadOnlyList _fromState; + + private readonly IReadOnlyDictionary _slotDescriptions; + + /// Creates the provider for one document's providers.knowledge block. + /// How many candidates and how many asks the document allows. + /// + /// The scope's fromState slots, in declaration order — the same order §8 step 4 walks, so + /// a deployer reads one ordering rather than two. + /// + /// + /// Each slot's description, or for a + /// slot the document describes with nothing but its own name. + /// + internal ClarificationProvider( + KnowledgeAmbiguityConfiguration ambiguity, + IReadOnlyList fromState, + IReadOnlyDictionary slotDescriptions) + { + ArgumentNullException.ThrowIfNull(ambiguity); + ArgumentNullException.ThrowIfNull(fromState); + ArgumentNullException.ThrowIfNull(slotDescriptions); + + _ambiguity = ambiguity; + _fromState = fromState; + _slotDescriptions = slotDescriptions; + } + + /// + protected override ValueTask ProvideAIContextAsync( + InvokingContext context, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(context); + + // K38: a deployment that configured itself never to ask must never reach the loop below — + // at maxAsks 0 or below, step 2's namedAsks < maxAsks test is false on the very first slot, + // which would otherwise let step 3's reset ask exactly one question in the one deployment + // that asked for none. + if (_ambiguity.MaxAsks <= 0 || TurnContextScope.For(context.Session) is null) + { + return new(new AIContext()); + } + + var ambients = TurnAmbients.Current; + if (ambients?.Clarifications is not { } clarifications || ambients.State is not { } state) + { + return new(new AIContext()); + } + + List messages = []; + + foreach (var slot in _fromState) + { + if (!state.IsUnfilled(slot)) + { + continue; + } + + var snapshot = clarifications.Read(slot); + if (snapshot.Pending is not { Count: > 0 } pending) + { + continue; + } + + if (Speak(clarifications, slot, pending, snapshot, first: messages.Count == 0) is { } text) + { + messages.Add(new ChatMessage(ChatRole.System, text)); + } + } + + return new(new AIContext { Messages = messages.Count > 0 ? messages : null }); + } + + /// §7's four-step evaluation for one pending slot. + /// The sentence to speak, or when this slot stays silent. + private string? Speak( + Clarifications clarifications, + string slot, + IReadOnlyList pending, + Clarifications.SlotSnapshot snapshot, + bool first) + { + var wouldName = Clarifications.LastNamed.For(pending, _ambiguity.MaxCandidates); + + // §7 step 1 (K37): the caller has already been asked exactly this. + if (wouldName.Names(snapshot.LastNamed)) + { + return null; + } + + var description = ClarificationText.DescriptionOf(slot, _slotDescriptions); + + if (snapshot.NamedAsks < _ambiguity.MaxAsks) + { + clarifications.Ask(slot, wouldName, spendsReset: false); + return ClarificationText.Instruction(description, pending, _ambiguity.MaxCandidates, first); + } + + // §7 step 3: namedAsks is at the cap and, having failed step 1, what would be named has + // changed. The one reset is spent here. + if (!snapshot.ResetSpent) + { + clarifications.Ask(slot, wouldName, spendsReset: true); + return ClarificationText.Instruction(description, pending, _ambiguity.MaxCandidates, first); + } + + return null; + } +} diff --git a/src/AgentCore.Application/Runtime/ClarificationText.cs b/src/AgentCore.Application/Runtime/ClarificationText.cs new file mode 100644 index 00000000..54f60454 --- /dev/null +++ b/src/AgentCore.Application/Runtime/ClarificationText.cs @@ -0,0 +1,110 @@ +namespace AgentCore.Application.Runtime; + +/// +/// The sentences §7 specifies for both ambiguity channels. One rule, two wordings: channel 1 rides a +/// standing turn instruction and must never claim to suppress a card the search already returned; +/// channel 2 rides an empty search result and may say so plainly. +/// +internal static class ClarificationText +{ + /// Reads the wording a slot is described by, for either channel's sentence. + /// 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. Both channels resolve through here, so the two sentences never disagree about + /// what the caller is being asked about. + /// + internal static string DescriptionOf(string slot, IReadOnlyDictionary descriptions) + { + ArgumentNullException.ThrowIfNull(slot); + ArgumentNullException.ThrowIfNull(descriptions); + + return descriptions.TryGetValue(slot, out var configured) && !string.IsNullOrEmpty(configured) + ? configured + : slot; + } + + /// Renders channel 1's sentence: the clarification, as a turn instruction (K29). + /// + /// 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. + /// + /// Whether this is the first such message the turn speaks. A second opens "Another thing…" rather + /// than repeating "One thing…", so two pending slots do not read as the same question twice. + /// + /// The sentence. + internal static string Instruction( + string description, IReadOnlyList candidates, int maxCandidates, bool first) + { + ArgumentNullException.ThrowIfNull(description); + ArgumentNullException.ThrowIfNull(candidates); + + if (candidates.Count == 1) + { + var confirm = first ? "One thing is not yet confirmed" : "Another thing is not yet confirmed"; + return $"{confirm}: {description} Everything found is for {candidates[0]}. " + + "Ask the caller whether that is what they have before giving advice specific to it."; + } + + var known = first ? "One thing is not yet known" : "Another thing is not yet known"; + + if (candidates.Count > maxCandidates) + { + return $"{known}: {description} Ask the caller, and do not give advice specific to one until " + + "they answer."; + } + + return $"{known}: {description} It is one of {JoinAlternatives(candidates)}. Ask the caller, and do " + + "not give advice that is specific to one until they answer. Anything that applies to all of " + + "them is still fair game."; + } + + /// Renders channel 2's sentence: the probe's note, as a search result. + /// + /// The slot's description, or the slot name when the caller has none — an apposition, for + /// the same reason 's does. + /// + /// 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); + + 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."; + } + + const string decides = "One thing decides the answer here and is not yet known"; + + if (candidates.Count > maxCandidates) + { + // "which" needs the list as its antecedent, the same way channel 1's over-cap form drops + // "Anything that applies to all of them" rather than leave "them" pointing at a list that + // is no longer there. + 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."; + } + + /// + /// Joins candidates as alternatives — "X or Y", or "X, Y, or Z" — the phrasing channel 1's "It is + /// one of" reads as. Channel 2's "It could be:" is a plain list instead (see ), + /// which is why the two channels do not share this helper. + /// + private static string JoinAlternatives(IReadOnlyList candidates) + => candidates.Count == 2 + ? $"{candidates[0]} or {candidates[1]}" + : string.Join(", ", candidates.Take(candidates.Count - 1)) + ", or " + candidates[^1]; +} diff --git a/src/AgentCore.Application/Runtime/Clarifications.cs b/src/AgentCore.Application/Runtime/Clarifications.cs new file mode 100644 index 00000000..ab90d9f5 --- /dev/null +++ b/src/AgentCore.Application/Runtime/Clarifications.cs @@ -0,0 +1,435 @@ +using AgentCore.Application.Calls; +using Microsoft.Agents.AI; + +namespace AgentCore.Application.Runtime; + +/// +/// One call's memory of what its ambiguity channels have asked and named, and the per-turn latch +/// that lets several search-tool calls in one turn share a single probe (K36, K41, K43). +/// +/// +/// Constructed once by and put on as the same +/// instance every turn, so a value the extractor path writes is read back by the factory's probe and +/// vice versa. A graph: pattern: concurrent row runs several participants against this same +/// instance at once, so every read and every write takes — there is no member on +/// this type that touches a field without it. Reads go through and writes through +/// , each taking the lock once for the whole snapshot or transition, so a +/// concurrent participant can never observe a slot half way through §7 or §8's compound updates. +/// +internal sealed class Clarifications +{ + private readonly Lock _gate = new(); + + private readonly Dictionary _slots = new(StringComparer.Ordinal); + + private Probe? _probe; + + /// Reads a consistent snapshot of one slot's six fields, as of one lock acquisition. + /// The slot's name. + /// + /// The snapshot, with this turn's staged ask folded over what is committed (see + /// ). 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); + + lock (_gate) + { + return Snapshot(GetOrAdd(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) + { + mutate(GetOrAdd(name)); + } + } + + /// + /// Records channel 1's §7 transition for one slot, to be kept only once the turn it belongs to + /// has actually answered the caller. + /// + /// The slot's name. + /// What this ask names to the caller (K37). + /// + /// Whether this is §7 step 3's one reset. A reset returns namedAsks to 1 rather than 0, + /// because 0 would buy an extra ask and make the bound 2 x maxAsks + 1. + /// + /// + /// shows the ask at once, because §7 step 1 and the probe's K41 skip both + /// have to act on it inside this same turn. It becomes permanent only at + /// , which the turn calls once it knows the caller heard the agent's own + /// words. A turn that ended in the fallback reply never put the question, so the next + /// drops the ask instead: charging it would silence that slot for the + /// rest of the call over a question nobody was asked. + /// + internal void Ask(string name, LastNamed named, bool spendsReset) + { + ArgumentNullException.ThrowIfNull(name); + + lock (_gate) + { + var state = GetOrAdd(name); + var current = Snapshot(state); + + state.StagedAsk = new StagedAsk( + named, + spendsReset ? 1 : current.NamedAsks + 1, + current.ResetSpent || spendsReset); + + state.AskedThisTurn = true; + } + } + + /// Makes every ask this turn staged permanent (see ). + internal void CommitAsks() + { + lock (_gate) + { + foreach (var state in _slots.Values) + { + if (state.StagedAsk is not { } ask) + { + continue; + } + + state.LastNamed = ask.Named; + state.NamedAsks = ask.NamedAsks; + state.ResetSpent = ask.ResetSpent; + state.StagedAsk = null; + } + } + } + + /// + /// Claims this turn's one probe search. Several search-tool calls in one turn, or several graph + /// participants sharing this call, 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 call + /// 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) + { + if (_probe is { } claimed) + { + return claimed.AsLoser(); + } + + _probe = new Probe( + new TaskCompletionSource>( + TaskCreationOptions.RunContinuationsAsynchronously), + won: true); + + return _probe; + } + } + + /// + /// Opens a new turn: clears K41's per-turn mark and any uncommitted ask on every slot, and 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 CallSession.BeginTurn and nowhere else. + /// CallSession.EnterAmbients reopens its ambient scope once per streaming step, and + /// clearing there instead would void K41's mark several times inside one streaming turn. + /// + internal void BeginTurn() + { + lock (_gate) + { + foreach (var state in _slots.Values) + { + state.AskedThisTurn = false; + state.StagedAsk = null; + } + + _probe = null; + } + } + + /// + /// Takes back what an edit-and-resend withdrew: every slot's pending list and its record of what + /// was last named to the caller. The ask counters are left alone — the caller heard what they + /// heard, and clearing them would let the withdrawn segment buy a fresh maxAsks budget. + /// + internal void Withdraw() + { + lock (_gate) + { + foreach (var state in _slots.Values) + { + state.Pending = null; + state.LastNamed = LastNamed.None; + } + } + } + + /// Reads what every slot has spent of its ask budget, for the call's stored state. + /// + /// One entry per slot that has spent anything. A slot that has never been asked about is left + /// out, so a call that reached no ambiguity stores nothing. + /// + internal IReadOnlyDictionary Spent() + { + lock (_gate) + { + Dictionary spent = new(StringComparer.Ordinal); + + foreach (var (name, state) in _slots) + { + // Committed only. A staged ask belongs to a turn that has not yet answered the + // caller, and a snapshot taken mid-turn must not carry a charge that turn may drop. + if (state.ProbeAsks == 0 && state.NamedAsks == 0 && !state.ResetSpent) + { + continue; + } + + spent[name] = new CallClarificationState + { + ProbeAsks = state.ProbeAsks, + NamedAsks = state.NamedAsks, + ResetSpent = state.ResetSpent, + }; + } + + return spent; + } + } + + /// Puts back what an earlier session of this call spent of its ask budget. + /// What read from that session. + /// + /// The pending lists and the record of what was last named are deliberately not restored: they + /// belong 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) + { + foreach (var (name, stored) in spent) + { + var state = GetOrAdd(name); + state.ProbeAsks = stored.ProbeAsks; + state.NamedAsks = stored.NamedAsks; + state.ResetSpent = stored.ResetSpent; + } + } + } + + /// Reads or creates one slot's state. Callers must already hold . + private SlotState GetOrAdd(string name) + { + if (!_slots.TryGetValue(name, out var state)) + { + state = new SlotState(); + _slots.Add(name, state); + } + + return state; + } + + private static SlotSnapshot Snapshot(SlotState state) + { + var ask = state.StagedAsk; + + return new( + state.Pending, + state.EffectiveLastNamed, + state.ProbeAsks, + ask?.NamedAsks ?? state.NamedAsks, + ask?.ResetSpent ?? state.ResetSpent, + state.AskedThisTurn); + } + + /// 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 exact candidate set last named. + Set, + + /// The candidate set was above maxCandidates, so no list was ever spoken. + TooMany, + } + + /// One turn's channel-1 ask, staged until the turn answers the caller (see ). + internal sealed record StagedAsk(LastNamed Named, int NamedAsks, bool ResetSpent); + + /// + /// 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; + + internal Probe( + TaskCompletionSource> payload, bool won) + { + _payload = payload; + Won = won; + } + + /// Whether this caller is the one that must run the search and publish its outcome. + internal bool Won { get; } + + /// 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); + + _payload.TrySetResult(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(); + + /// 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); + + /// 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); + } + + /// What a channel would record for one candidate set (K37). + /// The candidates that channel is about to name. + /// The document's maxCandidates. + /// + /// when the set is over the cap, so no list is spoken; otherwise the + /// exact set. Both ambiguity channels record through here rather than each deciding the cap + /// for itself, so channel 1's record and the probe's are always comparable — including 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)); + } + + /// + /// 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) + => Kind == other.Kind && (Kind != LastNamedKind.Set || Values!.SetEquals(other.Values!)); + } + + /// A consistent, point-in-time copy of one slot's six fields (see ). + internal readonly record struct SlotSnapshot( + IReadOnlyList? Pending, + LastNamed LastNamed, + int ProbeAsks, + int NamedAsks, + bool ResetSpent, + bool AskedThisTurn); + + /// + /// 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 IReadOnlyList? Pending; + + internal LastNamed LastNamed = LastNamed.None; + + internal int ProbeAsks; + + internal int NamedAsks; + + internal bool ResetSpent; + + internal bool AskedThisTurn; + + /// This turn's uncommitted channel-1 ask, or null when it has not asked. + internal StagedAsk? StagedAsk; + + /// + /// What the caller has most recently been told, this turn's uncommitted ask included. + /// + /// + /// The field alone is the committed record and lags a turn that has asked but not yet + /// answered. A writer inside an callback that has to compare against what + /// the caller would hear must read this, not . + /// + internal LastNamed EffectiveLastNamed => StagedAsk is { } ask ? ask.Named : LastNamed; + } +} diff --git a/src/AgentCore.Application/Runtime/OuterToolCall.cs b/src/AgentCore.Application/Runtime/OuterToolCall.cs index 1284c80d..6c5f2c2b 100644 --- a/src/AgentCore.Application/Runtime/OuterToolCall.cs +++ b/src/AgentCore.Application/Runtime/OuterToolCall.cs @@ -9,11 +9,20 @@ internal static class OuterToolCall internal static string? Current => TurnAmbients.Current?.OuterCallId; /// Opens the scope of one tool call over this flow of execution. - internal static IDisposable Enter(string callId) + /// The id of the tool call being opened. + /// + /// Whether a tool call was already open on this flow, so this one runs inside it. Reported from + /// here rather than read separately by the caller, because the outermost call is what owns the + /// ambient and a caller that read after this method would always see one. + /// + /// The scope. Disposing it puts back what was ambient before. + internal static IDisposable Enter(string callId, out bool nested) { ArgumentNullException.ThrowIfNull(callId); - return Current is not null ? NoOpScope.Instance : TurnAmbients.Amend(ambients => ambients with { OuterCallId = callId }); + nested = Current is not null; + + return nested ? NoOpScope.Instance : TurnAmbients.Amend(ambients => ambients with { OuterCallId = callId }); } /// A scope that puts nothing back, because it never changed anything. diff --git a/src/AgentCore.Application/Runtime/TurnAmbients.cs b/src/AgentCore.Application/Runtime/TurnAmbients.cs index fa11c639..1e7f81e6 100644 --- a/src/AgentCore.Application/Runtime/TurnAmbients.cs +++ b/src/AgentCore.Application/Runtime/TurnAmbients.cs @@ -40,6 +40,9 @@ internal sealed record TurnAmbients /// Gets what the turn may see of the knowledge base, or . public KnowledgeScope? Knowledge { get; init; } + /// Gets the call's ambiguity holder (K36), or inside a nested tool call (K42). + public Clarifications? Clarifications { get; init; } + /// Opens what a turn owns, and carries every other ambient through unchanged. /// The state document the call reads and writes. /// What this turn draws into, or when it has no screen. @@ -47,18 +50,21 @@ internal sealed record TurnAmbients /// What to do with a tool failure the run reports. /// The turn the tools are running inside. /// What this turn may see of the knowledge base, or when the document composes none. + /// The call's ambiguity holder. internal static IDisposable Enter( StateDocument state, TurnRenders? renders, TurnSources sources, Action onToolFailure, TurnContext context, - KnowledgeScope? knowledge) + KnowledgeScope? knowledge, + Clarifications clarifications) { ArgumentNullException.ThrowIfNull(state); ArgumentNullException.ThrowIfNull(sources); ArgumentNullException.ThrowIfNull(onToolFailure); ArgumentNullException.ThrowIfNull(context); + ArgumentNullException.ThrowIfNull(clarifications); var current = Ambient.Value ?? None; @@ -71,6 +77,7 @@ internal static IDisposable Enter( OnToolFailure = onToolFailure, Context = context, Knowledge = knowledge ?? current.Knowledge, + Clarifications = clarifications, }); } diff --git a/src/AgentCore.Application/Runtime/TurnContextScope.cs b/src/AgentCore.Application/Runtime/TurnContextScope.cs index 78831efb..c5a01be5 100644 --- a/src/AgentCore.Application/Runtime/TurnContextScope.cs +++ b/src/AgentCore.Application/Runtime/TurnContextScope.cs @@ -19,6 +19,15 @@ internal sealed record TurnContext /// Gets the id of the delegating tool are meant for. public string? ToolsFor { get; init; } + + /// + /// Gets whether this row's session carries the caller's own history — true on rows 1 and 2, false + /// on a graph row. §8 step 6 reads this to decide whether the probe may record what it named + /// (K39, drawn for the record rather than for the message): the probe runs inside a search + /// delegate that is never handed a session to compare, unlike 's + /// ReferenceEquals guard, so it reads this flag off the ambient instead. + /// + public bool CarriesHistory { get; init; } } /// diff --git a/src/AgentCore.Application/State/ExactStateValueLinker.cs b/src/AgentCore.Application/State/ExactStateValueLinker.cs new file mode 100644 index 00000000..ab74602b --- /dev/null +++ b/src/AgentCore.Application/State/ExactStateValueLinker.cs @@ -0,0 +1,274 @@ +using System.Globalization; +using System.Runtime.CompilerServices; +using System.Text; + +namespace AgentCore.Application.State; + +/// +/// The exact linker (K9): fold, bounded join, exact match, span resolution. There is no +/// trigram or embedding fallback — a near-tie leaves the slot unfilled and names the candidates +/// (K11) rather than guessing. +/// +/// +/// Tokenising is rather than a second copy of K31's +/// predicate; the vocabulary's fold-to-original map is built once at boot by +/// , so this type never folds a vocabulary value or checks it +/// for a collision itself. +/// +public sealed class ExactStateValueLinker : IStateValueLinker +{ + /// The longest run of tokens one candidate spelling may join. + private const int MaxRun = 4; + + /// + /// Separator runes that always break a join, regardless of whitespace. An enumerated list, not + /// a Unicode class: Po contains . and /, which §6 needs to join. + /// + private static readonly HashSet PhraseBreaks = [.. ",;:!?".EnumerateRunes()]; + + /// + /// One ordinally sorted copy of each view's normalised keys, memoised for as long as the view + /// itself lives. A view is immutable and a refresh swaps the reference (section 5), so an entry + /// can never describe a vocabulary that has since changed. + /// + private static readonly ConditionalWeakTable KeysInOrder = new(); + + /// + public string Name => "exact"; + + /// + public LinkResult Link(string mention, VocabularyView vocabulary, IReadOnlySet lastNamed) + { + ArgumentNullException.ThrowIfNull(mention); + ArgumentNullException.ThrowIfNull(vocabulary); + ArgumentNullException.ThrowIfNull(lastNamed); + + var (tokens, separators) = VocabularyFold.Tokenize(mention); + var candidates = BuildCandidates(tokens, separators); + var table = vocabulary.NormalisedToOriginal; + + // Driven by the candidates, not by the vocabulary: a mention yields at most four spellings + // per token, where the vocabulary may hold thousands of values. The intersection is the same + // either way round. + Dictionary> hits = new(StringComparer.Ordinal); + foreach (var (key, spans) in candidates) + { + if (table.ContainsKey(key)) + { + hits[key] = spans; + } + } + + var kept = Resolve(hits); + + if (kept.Count == 0) + { + return new LinkResult(LinkOutcome.NoMatch, []); + } + + if (kept.Count > 1) + { + return new LinkResult( + LinkOutcome.Ambiguous, + kept.Select(key => table[key]).Order(StringComparer.Ordinal).ToList()); + } + + var only = kept[0]; + var original = table[only]; + + if (lastNamed.Contains(original)) + { + return new LinkResult(LinkOutcome.Linked, [original]); + } + + var prefixedBy = PrefixedSiblings(vocabulary, only); + + if (prefixedBy.Count == 0) + { + return new LinkResult(LinkOutcome.Linked, [original]); + } + + // K21's tie-break did not apply, and `only` is a strict prefix of another value in the + // collection: the caller could mean either, so this stays a near-tie rather than a guess. + // The full set is re-sorted rather than just prepending `original` ahead of a sorted + // `prefixedBy`: a mixed-case vocabulary can make `original` compare greater than one of its + // own prefixed siblings under ordinal order (uppercase sorts before lowercase), which a bare + // prepend would leave out of order. + prefixedBy.Add(original); + prefixedBy.Sort(StringComparer.Ordinal); + return new LinkResult(LinkOutcome.Ambiguous, prefixedBy); + } + + /// + /// Every value whose normalised key has as a strict prefix, in the + /// collection's own spelling. + /// + /// + /// Under ordinal order every strict prefix extension of sorts after it + /// and the extensions are contiguous, so this is a binary search plus a walk over the matches + /// rather than a scan of the whole vocabulary. + /// + private static List PrefixedSiblings(VocabularyView vocabulary, string key) + { + var ordered = KeysInOrder.GetValue( + vocabulary, + view => [.. view.NormalisedToOriginal.Keys.Order(StringComparer.Ordinal)]); + + var found = Array.BinarySearch(ordered, key, StringComparer.Ordinal); + var scan = found < 0 ? ~found : found + 1; + + List siblings = []; + for (; scan < ordered.Length && ordered[scan].StartsWith(key, StringComparison.Ordinal); scan++) + { + siblings.Add(vocabulary.NormalisedToOriginal[ordered[scan]]); + } + + return siblings; + } + + /// + /// Discards a hit whose every span sits inside a span of some longer hit (K10) — tested per + /// span, so different spans of one hit may be swallowed by different longer hits, and no longer + /// hit need begin with the shorter one. + /// + private static List Resolve(Dictionary> hits) + { + List kept = []; + + foreach (var (hit, spans) in hits) + { + var longer = hits.Keys.Where(other => other.Length > hit.Length).ToList(); + var swallowed = longer.Count > 0 + && spans.All(span => longer.Any(other => hits[other].Any(outer => Contains(outer, span)))); + + if (!swallowed) + { + kept.Add(hit); + } + } + + return kept; + } + + private static bool Contains((int Start, int End) outer, (int Start, int End) inner) + => outer.Start <= inner.Start && inner.End <= outer.End; + + /// + /// Builds every candidate spelling §6 step 2 admits: every single token, and every contiguous + /// run of up to tokens whose separators are all joinable. Each run is tested + /// on its own — a run that fails does not stop a longer run starting at the same token. + /// + /// The mention's tokens, in order. + /// The runs between adjacent tokens — one fewer entry than . + /// The map from candidate spelling to every token span that produced it. + internal static Dictionary> BuildCandidates( + IReadOnlyList tokens, IReadOnlyList separators) + { + Dictionary> candidates = new(StringComparer.Ordinal); + + for (var start = 0; start < tokens.Count; start++) + { + var limit = Math.Min(start + MaxRun, tokens.Count); + + for (var end = start; end < limit; end++) + { + var run = new List(end - start + 1); + for (var index = start; index <= end; index++) + { + run.Add(tokens[index]); + } + + // Each run is tested on its own, against its own full token list — never by + // extending a shorter run's verdict. A separator's joinability can depend on a + // token elsewhere in the run (the digit rule), so a run of 3 can join where its + // own 2-token prefix would not. + if (end > start && !IsJoinable(separators, start, end, run)) + { + continue; + } + + var key = string.Concat(run); + if (!candidates.TryGetValue(key, out var spans)) + { + candidates[key] = spans = []; + } + + spans.Add((start, end)); + } + } + + return candidates; + } + + /// + /// Whether every separator inside [start, end) joins the whole run, by §6 step 2's three + /// rules in order: a phrase-breaking rune never joins; otherwise a separator with no whitespace + /// always joins; otherwise the run joins only when + /// allows it. + /// + private static bool IsJoinable(IReadOnlyList separators, int start, int end, IReadOnlyList run) + { + // The third rule reads the run and not the separator, so its verdict is the same for every + // separator here: taken at most once, and only once a separator actually needs it. + bool? runJoins = null; + + for (var index = start; index < end; index++) + { + var hasWhitespace = false; + + foreach (var rune in separators[index].EnumerateRunes()) + { + if (PhraseBreaks.Contains(rune) || Rune.IsControl(rune)) + { + return false; + } + + hasWhitespace = hasWhitespace || Rune.IsWhiteSpace(rune); + } + + if (!hasWhitespace) + { + continue; + } + + runJoins ??= RunJoinsAcrossWhitespace(run); + if (!runJoins.Value) + { + return false; + } + } + + return true; + } + + /// + /// §6 step 2's third rule: a whitespace separator joins the run only when the run carries a + /// digit, or every token in it is at least three runes long. + /// + private static bool RunJoinsAcrossWhitespace(IReadOnlyList run) + { + var allLongEnough = true; + + foreach (var token in run) + { + var runes = 0; + + foreach (var rune in token.EnumerateRunes()) + { + if (IsNumber(rune)) + { + return true; + } + + runes++; + } + + allLongEnough = allLongEnough && runes >= 3; + } + + return allLongEnough; + } + + private static bool IsNumber(Rune rune) => Rune.GetUnicodeCategory(rune) is + UnicodeCategory.DecimalDigitNumber or UnicodeCategory.LetterNumber or UnicodeCategory.OtherNumber; +} diff --git a/src/AgentCore.Application/State/IStateValueLinker.cs b/src/AgentCore.Application/State/IStateValueLinker.cs new file mode 100644 index 00000000..391bce44 --- /dev/null +++ b/src/AgentCore.Application/State/IStateValueLinker.cs @@ -0,0 +1,23 @@ +namespace AgentCore.Application.State; + +/// +/// Turns a caller's loose mention of a vocabulary: slot's value into the collection's own +/// spelling, or reports that it cannot be resolved without asking (K11, K12). +/// +public interface IStateValueLinker +{ + /// Gets the name a slot's vocabulary.linker resolves this linker by. + string Name { get; } + + /// Links one extractor mention against one slot's vocabulary. + /// The extractor's raw mention text. + /// The slot's vocabulary, sampled once at call open (K40). + /// + /// The candidate set actually spoken to the caller for this slot in this call — K37's record, + /// in the collection's own spelling — empty when nothing has been. Never a pending list a + /// channel installed but stayed silent about. A set, not a list: both ambiguity channels record + /// one under , and a linker only ever asks it for membership. + /// + /// The verdict. + LinkResult Link(string mention, VocabularyView vocabulary, IReadOnlySet lastNamed); +} diff --git a/src/AgentCore.Application/State/LinkResult.cs b/src/AgentCore.Application/State/LinkResult.cs new file mode 100644 index 00000000..e7a9a959 --- /dev/null +++ b/src/AgentCore.Application/State/LinkResult.cs @@ -0,0 +1,55 @@ +namespace AgentCore.Application.State; + +/// The three outcomes an can return (§6 step 4). +public enum LinkOutcome +{ + /// Nothing in the vocabulary matched. The slot stays unfilled. + NoMatch, + + /// Exactly one value matched, with no unresolved tie. + Linked, + + /// More than one value is a plausible match, and none can be preferred (K11). + Ambiguous, +} + +/// One linker verdict. +/// Which of the three outcomes this is. +/// +/// The matching values, in the collection's own spelling, sorted with +/// . +/// +/// +/// The candidate count does not match the outcome. is public, so a +/// host linker is arbitrary code; checking here makes the count an invariant the extractor can +/// index on rather than a promise it has to re-test. +/// +public sealed record LinkResult(LinkOutcome Outcome, IReadOnlyList Candidates) +{ + /// + /// Gets the matching values, in the collection's own spelling, sorted with + /// . carries none, + /// exactly one, and at + /// least two. + /// + public IReadOnlyList Candidates { get; init; } = Checked(Outcome, Candidates); + + private static IReadOnlyList Checked(LinkOutcome outcome, IReadOnlyList candidates) + { + ArgumentNullException.ThrowIfNull(candidates); + + var holds = outcome switch + { + LinkOutcome.NoMatch => candidates.Count == 0, + LinkOutcome.Linked => candidates.Count == 1, + LinkOutcome.Ambiguous => candidates.Count > 1, + _ => false, + }; + + return holds + ? candidates + : throw new ArgumentException( + $"a {outcome} verdict cannot carry {candidates.Count} candidates.", + nameof(candidates)); + } +} diff --git a/src/AgentCore.Application/State/StateDocument.cs b/src/AgentCore.Application/State/StateDocument.cs index 424c8eed..c5d34041 100644 --- a/src/AgentCore.Application/State/StateDocument.cs +++ b/src/AgentCore.Application/State/StateDocument.cs @@ -30,22 +30,43 @@ namespace AgentCore.Application.State; /// public sealed class StateDocument { + private static readonly IReadOnlyDictionary EmptyVocabulary = + new Dictionary(StringComparer.Ordinal); + private readonly ConcurrentDictionary _written = new(StringComparer.Ordinal); + private readonly IReadOnlyDictionary _vocabulary; + /// Creates the state of one call from the declared slots. /// The loaded document. /// The stage the call starts in, or when there is no policy. - public StateDocument(AgentCoreConfiguration configuration, string? stage = null) + /// + /// Every vocabulary: slot's domain, sampled once at call open (K40), or + /// when the caller has none to give. A slot missing from this map + /// refuses every write, the same as a slot missing from an enum:. + /// + public StateDocument( + AgentCoreConfiguration configuration, + string? stage = null, + IReadOnlyDictionary? vocabulary = null) { ArgumentNullException.ThrowIfNull(configuration); Configuration = configuration; Stage = stage ?? configuration.Policy?.Initial ?? string.Empty; + _vocabulary = vocabulary ?? EmptyVocabulary; } /// Gets the document this state was declared by. public AgentCoreConfiguration Configuration { get; } + /// + /// Gets every vocabulary: slot's domain, as it was sampled at call open (K40). The gate + /// below and 's linker read this one map, so neither can hold a + /// domain the other does not. + /// + internal IReadOnlyDictionary Vocabulary => _vocabulary; + /// Gets or sets the reserved stage slot. The policy runtime owns it. public string Stage { get; set; } @@ -125,6 +146,15 @@ public bool TryWrite(string slot, JsonNode? value) return false; } + // K1/K8: vocabulary: is enum:'s large-domain sibling, read from a provider instead of + // hand-written. The gate is the same shape — a slot missing from the snapshot (never + // sampled, or a refresh that never landed) refuses every value, exactly as an enum: slot + // with no members would. + if (declared.Vocabulary is not null && !IsVocabularyMember(slot, coerced)) + { + return false; + } + _written[slot] = coerced; return true; } @@ -146,6 +176,17 @@ private static bool IsMember(IReadOnlyList members, JsonNode? value) return false; } + // Through the fold map rather than a walk of Originals: a value is a member exactly when it + // folds to a key the collection stores and that key maps back to this same spelling, which is + // one dictionary probe instead of a scan of up to maxValues entries per write. It also reads + // the one map the linker reads, so the gate and the linker cannot disagree about the domain. + private bool IsVocabularyMember(string slot, JsonNode? value) + => _vocabulary.TryGetValue(slot, out var view) + && value is JsonValue text + && text.TryGetValue(out var written) + && view.NormalisedToOriginal.TryGetValue(VocabularyFold.Fold(written), out var original) + && string.Equals(original, written, StringComparison.Ordinal); + /// 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() diff --git a/src/AgentCore.Application/State/StateExtractor.cs b/src/AgentCore.Application/State/StateExtractor.cs index a38998fe..a0f58f9a 100644 --- a/src/AgentCore.Application/State/StateExtractor.cs +++ b/src/AgentCore.Application/State/StateExtractor.cs @@ -2,6 +2,7 @@ using System.Text.Json; using System.Text.Json.Nodes; using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Runtime; using Microsoft.Extensions.AI; namespace AgentCore.Application.State; @@ -37,17 +38,31 @@ public sealed class StateExtractor + "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 static readonly IReadOnlySet NothingNamed = new HashSet(StringComparer.Ordinal); + private readonly IChatClient _chatClient; private readonly ChatOptions _options; + private readonly StateValueLinkers _linkers; /// 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) + : this(configuration, chatClient, new StateValueLinkers([])) + { + } + + /// Creates the extractor with a linker registry (K12) for its vocabulary: slots. + /// The loaded document. + /// The model named by extractor.model. + /// The registry StateExtractor.Write resolves each slot's vocabulary.linker against. + /// The document declares no extractor: section. + internal StateExtractor(AgentCoreConfiguration configuration, IChatClient chatClient, StateValueLinkers linkers) { ArgumentNullException.ThrowIfNull(configuration); ArgumentNullException.ThrowIfNull(chatClient); + ArgumentNullException.ThrowIfNull(linkers); if (configuration.Extractor is null) { @@ -57,6 +72,7 @@ public StateExtractor(AgentCoreConfiguration configuration, IChatClient chatClie Configuration = configuration; _chatClient = chatClient; + _linkers = linkers; SlotNames = [.. configuration.State .Where(entry => entry.Value.Writer == StateWriter.Extractor) .Select(entry => entry.Key)]; @@ -144,13 +160,35 @@ public static JsonElement BuildSchema(AgentCoreConfiguration configuration) /// The finished turn, newest last. /// Cancels the model call. /// What the call did to the state. - public async Task ExtractAsync( + public Task ExtractAsync( + StateDocument state, + IEnumerable transcript, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(state); + ArgumentNullException.ThrowIfNull(transcript); + + return ExtractAsync(state, transcript, new Clarifications(), cancellationToken); + } + + /// + /// Runs one extractor call against the finished turn, then writes what it answered — the linker's + /// path over a vocabulary: slot's free text included (§6). + /// + /// The state of one call, which carries the vocabulary the linker resolves against. + /// The finished turn, newest last. + /// The call's ambiguity holder. reads and writes it. + /// Cancels the model call. + /// What the call 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); if (SlotNames.Count == 0) { @@ -170,7 +208,7 @@ public async Task ExtractAsync( return StateExtractionResult.Failed($"the extractor call failed: {exception.Message}"); } - return Write(state, response.Text); + return Write(state, response.Text, clarifications); } /// Writes one extractor reply into the state. @@ -181,6 +219,29 @@ public StateExtractionResult Write(StateDocument state, string? replyText) { ArgumentNullException.ThrowIfNull(state); + return Write(state, replyText, new Clarifications()); + } + + /// + /// Writes one extractor reply into the state, running §6's linker over every vocabulary: + /// slot's free-text answer first. + /// + /// The state of one call, which carries the vocabulary the linker resolves against. + /// The raw JSON the model returned. + /// + /// The call's ambiguity holder (K36). A Linked outcome that writes clears the slot's + /// pending list and its lastNamed record (K30); an Ambiguous outcome replaces the + /// pending list, stale or not; a NoMatch outcome touches neither. + /// + /// What the reply did to the state. + internal StateExtractionResult Write( + StateDocument state, + string? replyText, + Clarifications clarifications) + { + ArgumentNullException.ThrowIfNull(state); + ArgumentNullException.ThrowIfNull(clarifications); + if (string.IsNullOrWhiteSpace(replyText)) { return StateExtractionResult.Failed("the extractor returned an empty reply"); @@ -211,7 +272,17 @@ public StateExtractionResult Write(StateDocument state, string? replyText) continue; } - if (state.TryWrite(name, value.DeepClone())) + var declared = Configuration.State[name]; + + // Every answer to a vocabulary: slot goes through the linker, whatever JSON shape it + // arrived in. The schema asks for a string, but a model can answer 900 for a value + // spelled "900ENT", and letting that reach the gate directly would coerce it to "900" + // and skip §6's near-tie check entirely. + var wrote = declared.Vocabulary is { } vocabularyConfig + ? WriteLinked(state, name, value, vocabularyConfig, clarifications) + : WritePlain(state, name, value, clarifications); + + if (wrote) { filled++; } @@ -224,6 +295,93 @@ public StateExtractionResult Write(StateDocument state, string? replyText) return new StateExtractionResult(true, filled, left, rejected, null); } + /// The non-vocabulary: path: coerce and gate through as before. + private static bool WritePlain(StateDocument state, string slot, JsonNode value, Clarifications clarifications) + { + if (!state.TryWrite(slot, value.DeepClone())) + { + return false; + } + + ClearAmbiguity(clarifications, slot); + return true; + } + + /// §6's table: link the mention, then act on the outcome. + private bool WriteLinked( + StateDocument state, + string slot, + JsonNode value, + SlotVocabularyConfiguration vocabularyConfig, + Clarifications clarifications) + { + if (!state.Vocabulary.TryGetValue(slot, out var view)) + { + // No domain was sampled for this slot this call. The gate would refuse anything + // anyway, so there is nothing here for the linker to resolve against. + return false; + } + + if (!StateValueCoercion.TryCoerce(value, StateSlotType.String, out var coerced) + || coerced is not JsonValue text + || !text.TryGetValue(out var mention)) + { + return false; + } + + LinkResult result; + try + { + var linker = _linkers.Resolve(vocabularyConfig.Linker); + result = linker.Link(mention, view, SpokenCandidates(clarifications.Read(slot).LastNamed)); + } + catch (Exception exception) when (exception is not OperationCanceledException) + { + // State extraction must never drop a call. Section 8.7. A host linker is arbitrary + // code and an unregistered linker name throws from Resolve, so this refuses the one + // slot rather than letting either unwind the turn. + return false; + } + + switch (result.Outcome) + { + case LinkOutcome.Linked: + if (!state.TryWrite(slot, JsonValue.Create(result.Candidates[0]))) + { + return false; + } + + ClearAmbiguity(clarifications, slot); + return true; + + case LinkOutcome.Ambiguous: + var candidates = result.Candidates; + + // Overwrites whatever pending list was there, including a stale one channel 1 has + // already asked about. §7's own recovery path needs this: a caller who near-ties a + // second, different pair mid-conversation must not be silently dropped because the + // first pair is still sitting unresolved. Extraction runs after_reply, so this is + // the caller's own words beating a guess made earlier from search results. K41's + // fill-only-if-empty guard belongs to the probe, not the linker. + clarifications.Update(slot, s => s.Pending = candidates); + return false; + + default: + return false; + } + } + + /// K30: a successful write clears the slot's pending list and its lastNamed record together. + private static void ClearAmbiguity(Clarifications clarifications, string slot) + => clarifications.Update(slot, s => + { + s.Pending = null; + s.LastNamed = Clarifications.LastNamed.None; + }); + + private static IReadOnlySet SpokenCandidates(Clarifications.LastNamed lastNamed) + => lastNamed.Kind == Clarifications.LastNamedKind.Set ? lastNamed.Values! : NothingNamed; + private static string TypeName(StateSlotType slotType) => slotType switch { StateSlotType.Boolean => "boolean", diff --git a/src/AgentCore.Application/State/StateValueLinkers.cs b/src/AgentCore.Application/State/StateValueLinkers.cs new file mode 100644 index 00000000..27604fca --- /dev/null +++ b/src/AgentCore.Application/State/StateValueLinkers.cs @@ -0,0 +1,51 @@ +namespace AgentCore.Application.State; + +/// +/// The map from a vocabulary.linker name to the behind it +/// (K12). Always seeded with exact (K9) — the only linker that ships — so a host that binds +/// none still has a working registry. +/// +internal sealed class StateValueLinkers +{ + private readonly Dictionary _byName = new(StringComparer.Ordinal); + + /// Seeds the registry with exact and every linker a host registered. + /// The linkers a host bound with UseStateValueLinkers. + /// Two linkers, built-in or host-supplied, share a name. + internal StateValueLinkers(IEnumerable linkers) + { + ArgumentNullException.ThrowIfNull(linkers); + + Add(new ExactStateValueLinker()); + foreach (var linker in linkers) + { + Add(linker); + } + } + + /// Gets every name registered, for . + internal IReadOnlySet Names => _byName.Keys.ToHashSet(StringComparer.Ordinal); + + /// Resolves the linker one name points at. + /// A slot's vocabulary.linker value. + /// The linker. + /// No linker is registered under that name. + internal IStateValueLinker Resolve(string name) + { + ArgumentNullException.ThrowIfNull(name); + + return _byName.TryGetValue(name, out var linker) + ? linker + : throw new KeyNotFoundException($"no linker is registered under the name '{name}'."); + } + + private void Add(IStateValueLinker linker) + { + ArgumentNullException.ThrowIfNull(linker); + + if (!_byName.TryAdd(linker.Name, linker)) + { + throw new ArgumentException($"the linker name '{linker.Name}' is already registered.", nameof(linker)); + } + } +} diff --git a/src/AgentCore.Application/State/VocabularyCache.cs b/src/AgentCore.Application/State/VocabularyCache.cs new file mode 100644 index 00000000..308dc265 --- /dev/null +++ b/src/AgentCore.Application/State/VocabularyCache.cs @@ -0,0 +1,112 @@ +using System.Collections.Concurrent; +using System.Collections.Immutable; + +namespace AgentCore.Application.State; + +/// +/// One immutable per vocabulary: slot, behind a reference a +/// refresh swaps rather than mutates. +/// +/// +/// Section 5: a refresh builds a whole new view and replaces the reference, never mutating one in +/// place. That is what makes free to call once at call open and safe to +/// hold for the rest of the call — the dictionary a caller already read never changes under it, +/// and a live refresh on another slot cannot make that reader tear or throw. +/// +public sealed class VocabularyCache +{ + private readonly Lock _gate = new(); + private readonly TimeProvider _time; + private readonly ConcurrentDictionary _lastGoodAt = new(StringComparer.Ordinal); + private volatile ImmutableDictionary _views = ImmutableDictionary.Empty; + + /// Creates an empty cache. + /// Where comes from, or for the system clock. + public VocabularyCache(TimeProvider? timeProvider = null) => _time = timeProvider ?? TimeProvider.System; + + /// Reads every slot's current vocabulary. The result does not change as later refreshes land. + /// The map from slot name to its view. A slot has never been called for is absent. + public IReadOnlyDictionary Snapshot() => _views; + + /// Reads when a slot's vocabulary was last successfully built. + /// The slot name. + /// The time of the last successful , or when there has been none. + public DateTimeOffset? LastGoodAt(string slot) + { + ArgumentNullException.ThrowIfNull(slot); + return _lastGoodAt.TryGetValue(slot, out var at) ? at : null; + } + + /// Builds one slot's vocabulary from a facet read and installs it, or leaves the slot as it was. + /// The slot the values were read for. + /// The distinct values the facet read returned, before the wildcard sentinel is stripped. + /// The limit the read was made with — the same value passed as the read's own limit. + /// + /// The wildcard sentinel to strip before folding (K6), or when this slot carries none. + /// + /// + /// is below 2, which is the same floor + /// ConfigurationValidator holds the document to: a read of fewer than two values could + /// never be told apart from a truncated one, so every call would throw. + /// + /// + /// fails one of section 10's four degenerate-read checks: its raw count + /// reaches ; it is empty once is + /// stripped; two surviving values fold to the same string; or one folds to the empty string. The + /// slot is left unchanged. + /// + public void Replace(string slot, IReadOnlyList values, int maxValues, string? wildcardValue = null) + { + ArgumentNullException.ThrowIfNull(slot); + ArgumentNullException.ThrowIfNull(values); + ArgumentOutOfRangeException.ThrowIfLessThan(maxValues, 2); + + // The raw count, before the sentinel is stripped: this answers "did the read hit its own + // limit", which is a fact about what Qdrant returned, not about which of those values + // happens to be the wildcard. K6 only orders the strip ahead of the collision checks. + if (values.Count >= maxValues) + { + throw VocabularyException.Truncated(slot, maxValues); + } + + var survivors = wildcardValue is null + ? values + : values.Where(value => !string.Equals(value, wildcardValue, StringComparison.Ordinal)).ToList(); + + if (survivors.Count == 0) + { + throw VocabularyException.NoValues(slot); + } + + Dictionary normalisedToOriginal = new(survivors.Count, StringComparer.Ordinal); + + foreach (var original in survivors) + { + var normalised = VocabularyFold.Fold(original); + + if (normalised.Length == 0) + { + throw VocabularyException.FoldsToEmpty(slot, original); + } + + if (normalisedToOriginal.TryGetValue(normalised, out var existing)) + { + throw VocabularyException.FoldingCollision(slot, existing, original, normalised); + } + + normalisedToOriginal[normalised] = original; + } + + VocabularyView view = new() + { + NormalisedToOriginal = normalisedToOriginal, + Originals = [.. survivors], + }; + + lock (_gate) + { + _views = _views.SetItem(slot, view); + _lastGoodAt[slot] = _time.GetUtcNow(); + } + } +} diff --git a/src/AgentCore.Application/State/VocabularyException.cs b/src/AgentCore.Application/State/VocabularyException.cs new file mode 100644 index 00000000..f59e00c7 --- /dev/null +++ b/src/AgentCore.Application/State/VocabularyException.cs @@ -0,0 +1,97 @@ +using System.Globalization; + +namespace AgentCore.Application.State; + +/// +/// The one exception throws for each of section 10's four +/// degenerate reads. +/// +/// +/// Boot fails a slot's read rather than starting an agent whose vocabulary can never work: a read +/// that hit its own limit cannot be told from a complete one, two ids that fold alike could never +/// be told apart by a caller who says either, and an id that folds to nothing could never be +/// linked or gated at all. Turning this into a configuration error with the slot's resolved +/// document pointer belongs to the startup wiring that knows that path, not to the cache. +/// +public sealed class VocabularyException : Exception +{ + private const string DefaultMessage = "A slot's vocabulary could not be built."; + + /// Creates an exception that names no slot. + public VocabularyException() + : base(DefaultMessage) => Slot = string.Empty; + + /// Creates an exception with a plain message. + /// The message a human reads. + public VocabularyException(string message) + : base(message) => Slot = string.Empty; + + /// Creates an exception with a plain message and an inner cause. + /// The message a human reads. + /// The cause. + public VocabularyException(string message, Exception? innerException) + : base(message, innerException) => Slot = string.Empty; + + private VocabularyException(string slot, string message) + : base(message) => Slot = slot; + + /// Gets the slot the failed vocabulary belongs to, or an empty string. + public string Slot { get; } + + /// Builds the failure for a read with no candidate values once the wildcard sentinel is stripped. + /// The slot the vocabulary belongs to. + /// The failure. + public static VocabularyException NoValues(string slot) + { + ArgumentNullException.ThrowIfNull(slot); + return new VocabularyException( + slot, + $"the vocabulary for slot '{slot}' has no values once the wildcard sentinel is stripped. " + + "A slot with no candidates can never be gated or linked."); + } + + /// Builds the failure for a read whose count reached or passed the limit it was read with. + /// The slot the vocabulary belongs to. + /// The limit the read was made with. + /// The failure. + public static VocabularyException Truncated(string slot, int maxValues) + { + ArgumentNullException.ThrowIfNull(slot); + return new VocabularyException( + slot, + $"the vocabulary for slot '{slot}' returned at least {maxValues.ToString(CultureInfo.InvariantCulture)} " + + "values, its configured maxValues. That count cannot be told apart from a truncated read."); + } + + /// Builds the failure for two values that normalise to the same string. + /// The slot the vocabulary belongs to. + /// The value already in the map. + /// The value that collided with it. + /// The normalised form both values share. + /// The failure. + public static VocabularyException FoldingCollision(string slot, string first, string second, string normalised) + { + ArgumentNullException.ThrowIfNull(slot); + ArgumentNullException.ThrowIfNull(first); + ArgumentNullException.ThrowIfNull(second); + ArgumentNullException.ThrowIfNull(normalised); + return new VocabularyException( + slot, + $"the vocabulary for slot '{slot}' has two values that normalise alike: '{first}' and '{second}' " + + $"both fold to '{normalised}'. A caller who says either could never be told apart."); + } + + /// Builds the failure for a value that normalises to the empty string. + /// The slot the vocabulary belongs to. + /// The value that folded away. + /// The failure. + public static VocabularyException FoldsToEmpty(string slot, string value) + { + ArgumentNullException.ThrowIfNull(slot); + ArgumentNullException.ThrowIfNull(value); + return new VocabularyException( + slot, + $"the vocabulary for slot '{slot}' has a value that normalises to the empty string: '{value}'. " + + "It could never be linked or gated."); + } +} diff --git a/src/AgentCore.Application/State/VocabularyFold.cs b/src/AgentCore.Application/State/VocabularyFold.cs new file mode 100644 index 00000000..03ce0026 --- /dev/null +++ b/src/AgentCore.Application/State/VocabularyFold.cs @@ -0,0 +1,103 @@ +using System.Globalization; +using System.Text; + +namespace AgentCore.Application.State; + +/// +/// The K31 fold: NFC, invariant lower case, then keep only letters, numbers and marks. One +/// predicate drives both the vocabulary's fold and the mention's tokeniser, so a caller can never +/// see a class the vocabulary was not also normalised by. +/// +/// +/// throughout, never : an astral codepoint is a surrogate +/// pair, and classifying each half separately reads both as +/// — not a kept category — which would silently drop the codepoint instead of keeping it whole. +/// +internal static class VocabularyFold +{ + /// Normalises one vocabulary value or mention span to its comparable form. + /// The original string. + /// NFC, lower-invariant, letters/numbers/marks only. Empty when nothing survives. + internal static string Fold(string value) + { + ArgumentNullException.ThrowIfNull(value); + + var composed = value.Normalize(NormalizationForm.FormC).ToLowerInvariant(); + StringBuilder folded = new(composed.Length); + Span utf16 = stackalloc char[2]; + + foreach (var rune in composed.EnumerateRunes()) + { + if (Keep(rune)) + { + folded.Append(utf16[..rune.EncodeToUtf16(utf16)]); + } + } + + return folded.ToString(); + } + + /// Splits a mention into the runs would keep, and the runs between them it would drop. + /// The extractor's raw mention text. + /// + /// Tokens: the maximal runs of kept runes, each already folded, in order. + /// Separators: the runs of dropped runes strictly between two tokens — one fewer than + /// the token count. A leading or trailing run of dropped runes bounds nothing, so it is not + /// reported. + /// + internal static (IReadOnlyList Tokens, IReadOnlyList Separators) Tokenize(string mention) + { + ArgumentNullException.ThrowIfNull(mention); + + var composed = mention.Normalize(NormalizationForm.FormC).ToLowerInvariant(); + List tokens = []; + List separators = []; + StringBuilder buffer = new(); + Span utf16 = stackalloc char[2]; + var inToken = false; + var sawToken = false; + + foreach (var rune in composed.EnumerateRunes()) + { + var kept = Keep(rune); + if (kept != inToken) + { + if (inToken) + { + tokens.Add(buffer.ToString()); + sawToken = true; + } + else if (sawToken) + { + // A leading run of dropped runes bounds no token on its left, so only a run + // that follows one is a separator. + separators.Add(buffer.ToString()); + } + + buffer.Clear(); + inToken = kept; + } + + buffer.Append(utf16[..rune.EncodeToUtf16(utf16)]); + } + + if (inToken) + { + tokens.Add(buffer.ToString()); + } + + return (tokens, separators); + } + + private static bool Keep(Rune rune) => Rune.GetUnicodeCategory(rune) is + UnicodeCategory.UppercaseLetter or + UnicodeCategory.LowercaseLetter or + UnicodeCategory.TitlecaseLetter or + UnicodeCategory.ModifierLetter or + UnicodeCategory.OtherLetter or + UnicodeCategory.DecimalDigitNumber or + UnicodeCategory.LetterNumber or + UnicodeCategory.OtherNumber or + UnicodeCategory.NonSpacingMark or + UnicodeCategory.SpacingCombiningMark; +} diff --git a/src/AgentCore.Application/State/VocabularyView.cs b/src/AgentCore.Application/State/VocabularyView.cs new file mode 100644 index 00000000..a1fd1f9b --- /dev/null +++ b/src/AgentCore.Application/State/VocabularyView.cs @@ -0,0 +1,19 @@ +namespace AgentCore.Application.State; + +/// +/// One slot's vocabulary: every original value the collection stores, and the map from each +/// value's normalised form back to that original. +/// +/// +/// Immutable, so a snapshot taken once at call open never changes under the call that holds it — +/// section 5's requirement that a refresh landing mid-call cannot make the gate and the linker +/// disagree, because both read the one reference handed out. +/// +public sealed record VocabularyView +{ + /// Gets the map from a value's normalised form (the VocabularyFold.Fold result) back to the original string. + public required IReadOnlyDictionary NormalisedToOriginal { get; init; } + + /// Gets every original value, in the order the read returned them, with the wildcard sentinel already stripped. + public required IReadOnlyList Originals { get; init; } +} diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs index f179f524..3e0722d2 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs @@ -8,9 +8,11 @@ using AgentCore.Application.Ports; using AgentCore.Application.Runtime; using AgentCore.Application.Secrets; +using AgentCore.Application.State; using AgentCore.Application.Tools.Binding; using AgentCore.Application.Tools.Registry; using AgentCore.AspNetCore.DependencyInjection.Startup; +using AgentCore.AspNetCore.Sessions; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Options; @@ -151,12 +153,22 @@ internal T Release(T resource) /// One ${secret:name} reference resolves to nothing. internal async ValueTask BootAsync(CancellationToken cancellationToken) { - var configuration = ConfigurationStartup.Load(_options); + var (configuration, configurationWarnings) = ConfigurationStartup.Load(_options); + + HashSet registeredLinkers = new(StringComparer.Ordinal) { SlotVocabularyConfiguration.DefaultLinker }; + registeredLinkers.UnionWith(_options.StateValueLinkers.Select(static linker => linker.Name)); + ConfigurationValidator.ValidateLinkerNames(configuration, registeredLinkers); 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()); + } + var secrets = await SecretsStartup .ResolveAsync(configuration, _options, cancellationToken) .ConfigureAwait(false); @@ -180,6 +192,15 @@ internal async ValueTask BootAsync(CancellationToken cancellationToken) cancellationToken) .ConfigureAwait(false)); + VocabularyCache vocabulary = new(_options.TimeProvider); + + await KnowledgeStartup + .ApplyVocabularyAsync( + configuration, knowledge, vocabulary, _loggers.CreateLogger(typeof(KnowledgeStartup)), cancellationToken) + .ConfigureAwait(false); + + StartVocabularyRefresh(configuration, knowledge, vocabulary, cancellationToken); + var chatClients = Track(await ChatClientStartup .BuildAsync(_options, startup, cancellationToken) .ConfigureAwait(false)); @@ -226,7 +247,7 @@ internal async ValueTask BootAsync(CancellationToken cancellationToken) var seams = CallSeamStartup.Build(configuration, _options); var call = await CallSessionStartup - .OpenAsync(this, configuration, _options, graph, _loggers, cancellationToken) + .OpenAsync(this, configuration, _options, graph, vocabulary, _loggers, cancellationToken) .ConfigureAwait(false); _state = new BootState( @@ -292,6 +313,63 @@ private async ValueTask CloseAsync() } } + /// + /// Starts one per vocabulary: slot that declares a + /// refreshSeconds above zero. 0 means boot only (§4), so those slots start none. + /// + /// The loaded document. + /// The port built, or . + /// The cache every refresh installs into — the same one every call session reads. + /// Passed to each service's own StartAsync. + private void StartVocabularyRefresh( + AgentCoreConfiguration configuration, + IKnowledgeRetrievalPort? knowledge, + VocabularyCache vocabulary, + CancellationToken cancellationToken) + { + if (knowledge is not IFacetVocabularyPort port) + { + return; + } + + var scope = configuration.Providers?.Knowledge?.Scope; + if (scope is null || ScopeTemplate.Parse(scope.Template) is not { } template) + { + return; + } + + var wildcard = scope.Wildcard; + + foreach (var (slotName, slot) in configuration.State) + { + if (slot.Vocabulary is not { RefreshSeconds: > 0 } vocab) + { + continue; + } + + var path = template.Resolve(slotName); + var wildcardValue = wildcard is not null && wildcard.Facets.Contains(slotName, StringComparer.Ordinal) + ? wildcard.Value + : null; + + var service = Track(new VocabularyRefreshService( + slotName, + path, + vocab.MaxValues, + wildcardValue, + vocab.RefreshSeconds, + port, + vocabulary, + _options.TimeProvider ?? TimeProvider.System, + _loggers.CreateLogger())); + + // BackgroundService.StartAsync only arms the loop — it runs ExecuteAsync through + // Task.Run and returns immediately, so awaiting it here would not wait for a single + // refresh, only for the arm itself. + _ = service.StartAsync(cancellationToken); + } + } + private static InvalidOperationException NotStarted() => new( "AgentCore has not booted: the document is loaded, and every adapter it names is opened, " @@ -314,3 +392,16 @@ private sealed record BootState( RequestDelegate? CallHandler, string? CallUnroutable); } + +/// 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/AgentCoreOptions.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs index f43046c4..03e92b82 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs @@ -2,6 +2,7 @@ using AgentCore.Application.Knowledge; using AgentCore.Application.Llm; using AgentCore.Application.Ports; +using AgentCore.Application.State; using AgentCore.Application.Tools.Binding; using Microsoft.Agents.AI; using Microsoft.Extensions.Logging; @@ -71,6 +72,9 @@ public sealed class AgentCoreOptions /// Gets the speech vendors the host registered, or . internal IReadOnlyList? Speech { get; private set; } + /// Gets the linkers a slot's vocabulary.linker may name, beyond the built-in exact. + internal IReadOnlyList StateValueLinkers { get; private set; } = []; + /// Gets the folder that holds the SKILL.md directories, or . internal string? SkillsPath { get; private set; } @@ -236,6 +240,16 @@ public AgentCoreOptions UseSpeech(params ISpeechAdapter[] adapters) return this; } + /// Binds the state value linkers, and a slot's vocabulary.linker names one by its . + /// The linkers this host adds beyond the built-in exact. + /// These options, so a host chains its calls. + public AgentCoreOptions UseStateValueLinkers(params IStateValueLinker[] linkers) + { + ArgumentNullException.ThrowIfNull(linkers); + StateValueLinkers = linkers; + return this; + } + /// Binds the folder that holds this host's SKILL.md directories. public AgentCoreOptions UseSkills(string path) { diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/CallSessionStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/CallSessionStartup.cs index 9ff41f1e..0ca801f2 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/CallSessionStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/CallSessionStartup.cs @@ -3,6 +3,7 @@ using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Ports; using AgentCore.Application.Runtime; +using AgentCore.Application.State; using Microsoft.Extensions.Logging; namespace AgentCore.AspNetCore.DependencyInjection.Startup; @@ -22,6 +23,7 @@ internal static class CallSessionStartup /// The loaded document. It carries providers.audit. /// The options the host filled. It carries the audit vendors, the clock, and any observer. /// The compiled graph and the seams step 5 made. + /// The cache KnowledgeStartup.ApplyVocabularyAsync filled. /// The factory the session and the audit queue take their loggers from. /// Cancels the store open. /// The session factory, the agent shim, and the queue in front of the store. @@ -30,6 +32,7 @@ internal static async ValueTask OpenAsync( AgentCoreConfiguration configuration, AgentCoreOptions options, CompiledGraph graph, + VocabularyCache vocabulary, ILoggerFactory loggers, CancellationToken cancellationToken) { @@ -53,10 +56,11 @@ internal static async ValueTask OpenAsync( CallSessionFactory sessions = new( graph.Compiled, graph.Guards, - CallSessionFactory.CreateExtractor(graph.Compiled, graph.ChatClients), + CallSessionFactory.CreateExtractor(graph.Compiled, graph.ChatClients, options.StateValueLinkers), options.TimeProvider, sessionLogger, - CallObservers.Standard(auditSink, sessionLogger, options.Observers)); + CallObservers.Standard(auditSink, sessionLogger, options.Observers), + vocabulary); return new CallSessionSeam(sessions, new AgentCoreAgent(sessions, configuration.Name), auditSink); } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConfigurationStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConfigurationStartup.cs index f669714c..0c0a4ecd 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConfigurationStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/ConfigurationStartup.cs @@ -4,6 +4,16 @@ 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 two ambiguity-and-vocabulary +/// warnings (K33, K39). 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 { @@ -11,19 +21,20 @@ internal static class ConfigurationStartup /// The options the host filled. /// /// The loaded document, which has passed every check of section 8.5 except tool-reference - /// resolution. Decision 15 runs that check after discovery, in the composition root, against the - /// ids the tool registry actually serves — so an MCP-discovered id can satisfy a 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 AgentCoreConfiguration Load(AgentCoreOptions options) + internal static ConfigurationLoadResult Load(AgentCoreOptions options) { var configuration = LoadDocument(options); - ConfigurationValidator.ValidateStructure(configuration); - return configuration; + var result = ConfigurationValidator.ValidateStructure(configuration); + return new ConfigurationLoadResult(configuration, result.Warnings); } /// Reads the one document the options name. diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs index 342d3579..d40b4f8c 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs @@ -1,8 +1,12 @@ +using System.Text; using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; using AgentCore.Application.Ports; +using AgentCore.Application.State; using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; namespace AgentCore.AspNetCore.DependencyInjection; @@ -56,4 +60,217 @@ internal static class KnowledgeStartup /// when at least one agent reads the knowledge base. private static bool AnyAgentDeclares(AgentCoreConfiguration configuration) => configuration.Agents is { } agents && AgentKnowledge.AnyDeclared(agents); + + /// + /// Section 10: reads every vocabulary: slot's domain into , + /// K44's Unicode probe ahead of those reads, and K48's per-wildcard.facets member check. + /// + /// The loaded document. Already past checks 2 to 8. + /// The port built, or . + /// The cache every successful read is installed into. + /// Where K28's and K48's warnings go. + /// Cancels every read. + /// + /// K44's probe, or for the real one (). A + /// test drives the outcome through this seam: the AspNetCore test host already runs under + /// InvariantGlobalization=true, which makes the non-composing case the ambient default and + /// the composing case unreachable without one. + /// + /// + /// A vocabulary: slot is declared and is not an + /// (K27); the runtime cannot compose Unicode and a slot does + /// not declare assumeNormalized: true (K44); or a slot's read is degenerate (K4, K31). + /// + internal static async ValueTask ApplyVocabularyAsync( + AgentCoreConfiguration configuration, + IKnowledgeRetrievalPort? knowledge, + VocabularyCache vocabulary, + ILogger logger, + CancellationToken cancellationToken, + Func? composesUnicode = null) + { + ArgumentNullException.ThrowIfNull(configuration); + ArgumentNullException.ThrowIfNull(vocabulary); + ArgumentNullException.ThrowIfNull(logger); + + var vocabularySlots = configuration.State + .Where(entry => entry.Value.Vocabulary is not null) + .ToList(); + + var wildcard = configuration.Providers?.Knowledge?.Scope.Wildcard; + var wildcardFacets = wildcard?.Facets ?? []; + + if (vocabularySlots.Count == 0 && wildcardFacets.Count == 0) + { + return; + } + + if (knowledge is not IFacetVocabularyPort port) + { + if (vocabularySlots.Count == 0) + { + // A wildcard-only document predates this design (the 2026-09-01 wildcard plan), and + // K27's refusal is scoped to a document that declares vocabulary:. Forcing every such + // deployment to also implement IFacetVocabularyPort would break K19's byte-identity + // promise for a feature this design never touches. + return; + } + + var reason = knowledge is null + ? "no knowledge port was built, so there is nothing to read a facet vocabulary from" + : $"the built port ({knowledge.GetType().Name}) does not implement {nameof(IFacetVocabularyPort)}"; + + throw FailSlots( + vocabularySlots.Select(entry => entry.Key), + $"declares vocabulary:, and {reason}. A vocabulary: read needs " + + $"{nameof(IFacetVocabularyPort)}.{nameof(IFacetVocabularyPort.ReadAsync)}, which a " + + "host-bound port (UseKnowledgeRetrieval), the composite CompositeKnowledgeStoreFactory " + + "builds from providers.knowledge.kind, and a document with no registered store adapter " + + "can each fail to serve."); + } + + var template = ScopeTemplate.Parse(configuration.Providers?.Knowledge?.Scope.Template) + ?? throw new InvalidOperationException( + "a vocabulary: or wildcard.facets read needs providers.knowledge.scope.template, and " + + "this document names none. Check 5 of section 8.5 should have refused this document " + + "before boot ever reached this read."); + + if (vocabularySlots.Count > 0) + { + if (!(composesUnicode ?? ComposesUnicode)()) + { + var offending = vocabularySlots + .Where(entry => !entry.Value.Vocabulary!.AssumeNormalized) + .Select(entry => entry.Key) + .ToList(); + + if (offending.Count > 0) + { + throw FailSlots( + offending, + "declares vocabulary:, and this runtime cannot compose Unicode: " + + "InvariantGlobalization is enabled and string.Normalize is a no-op, so two " + + "spellings of one id that only differ by composition would never fold alike " + + "and section 10's collision check would never fire. Set InvariantGlobalization " + + "to false to gain ICU, or declare vocabulary.assumeNormalized: true if every id " + + "in the collection and every mention the extractor emits is already NFC."); + } + } + + foreach (var (slotName, slot) in vocabularySlots) + { + var vocab = slot.Vocabulary!; + var path = template.Resolve(slotName); + var values = await port.ReadAsync(path, vocab.MaxValues, cancellationToken).ConfigureAwait(false); + var wildcardValue = wildcardFacets.Contains(slotName, StringComparer.Ordinal) + ? wildcard!.Value + : null; + + try + { + vocabulary.Replace(slotName, values, vocab.MaxValues, wildcardValue); + } + catch (VocabularyException degenerate) + { + throw Fail( + ConfigurationError.AppendPointer(StatePointer(slotName), "vocabulary"), + $"{degenerate.Message} Read at path '{path}'.", + degenerate); + } + + if (vocabulary.Snapshot().TryGetValue(slotName, out var view) && view.Originals.Count == 1) + { + KnowledgeStartupLog.SingleValueVocabulary(logger, slotName, view.Originals[0]); + } + } + } + + foreach (var facet in wildcardFacets) + { + var path = template.Resolve(facet); + + IReadOnlyList sample; + try + { + sample = await port.ReadAsync(path, 2, cancellationToken).ConfigureAwait(false); + } + catch (Exception fault) when (fault is not OperationCanceledException) + { + // K48 sits under "warned, not refused": a facet whose store cannot serve this small + // sample read (for example, no keyword payload index at this path) must not turn a + // deployment that was booting into one that cannot. + KnowledgeStartupLog.WildcardFacetCheckFailed(logger, facet, path, fault); + continue; + } + + if (!sample.Contains(wildcard!.Value, StringComparer.Ordinal)) + { + KnowledgeStartupLog.WildcardFacetMissingStar(logger, facet, path); + } + } + } + + /// + /// K44's probe: whether this runtime can compose Unicode. Built from escape sequences, never + /// typed characters — a typed version reads identically and silently reports a false pass, + /// because the source file reaches disk already pre-composed (section 10). + /// + /// when actually composes. + internal static bool ComposesUnicode() => "\u0041\u030A".Normalize(NormalizationForm.FormC) == "\u00C5"; + + private static string StatePointer(string slot) => ConfigurationError.AppendPointer("/state", slot); + + private static ConfigurationLoadException Fail(string pointer, string message, Exception? inner = null) + => new( + new ConfigurationError { Pointer = pointer, Message = message, Check = ConfigurationCheck.ReferenceResolution }, + inner); + + private static ConfigurationLoadException FailSlots(IEnumerable slots, string reasonAfterSlotName) + => new(slots.Select(slot => new ConfigurationError + { + Pointer = ConfigurationError.AppendPointer(StatePointer(slot), "vocabulary"), + Message = $"the slot '{slot}' {reasonAfterSlotName}", + Check = ConfigurationCheck.ReferenceResolution, + }).ToList()); +} + +/// Every warning writes. +internal static partial class KnowledgeStartupLog +{ + /// A slot's vocabulary read back exactly one value (K28). + /// The boot logger. + /// The slot the vocabulary belongs to. + /// The one value. + [LoggerMessage( + EventId = 1, + Level = LogLevel.Warning, + Message = "the vocabulary for slot '{Slot}' has exactly one value: '{Value}'. The gate and " + + "the linker still work; only the ambiguity half is inert, because one value can never " + + "produce more than a confirm question.")] + public static partial void SingleValueVocabulary(ILogger logger, string slot, string value); + + /// A wildcard.facets member's collection holds no * value (K48). + /// The boot logger. + /// The facet key. + /// The resolved payload path the read used. + [LoggerMessage( + EventId = 2, + Level = LogLevel.Warning, + Message = "the wildcard facet '{Facet}' has no '*' value in the collection at '{Path}'. While " + + "it is unfilled, its own wildcard condition matches nothing, so no search and no probe " + + "of another facet can return a card. Fill it from a writer: const slot, or take " + + "'{Facet}' out of wildcard.facets.")] + public static partial void WildcardFacetMissingStar(ILogger logger, string facet, string path); + + /// A wildcard.facets member's own K48 read faulted (warned, not refused). + /// The boot logger. + /// The facet key. + /// The resolved payload path the read used. + /// The cause. + [LoggerMessage( + EventId = 3, + Level = LogLevel.Warning, + Message = "the K48 check for wildcard facet '{Facet}' could not run: the read at '{Path}' " + + "failed. Boot continues; the missing-'*'-value check is skipped for this facet only.")] + public static partial void WildcardFacetCheckFailed(ILogger logger, string facet, string path, Exception exception); } diff --git a/src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt b/src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt index 6a65df59..2059545f 100644 --- a/src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt +++ b/src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt @@ -39,6 +39,7 @@ AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.UseObservers(params Ag AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.UseSkills(Microsoft.Agents.AI.AgentSkillsSource! source) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions! AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.UseSkills(string! path) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions! AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.UseSpeech(params AgentCore.Application.Ports.ISpeechAdapter![]! adapters) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions! +AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.UseStateValueLinkers(params AgentCore.Application.State.IStateValueLinker![]! linkers) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions! AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.UseTelemetry(params AgentCore.Application.Ports.ITelemetryAdapter![]! adapters) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions! AgentCore.AspNetCore.DependencyInjection.AgentCoreServiceCollectionExtensions AgentCore.AspNetCore.DependencyInjection.AgentCoreStartup diff --git a/src/AgentCore.AspNetCore/Sessions/VocabularyRefreshService.cs b/src/AgentCore.AspNetCore/Sessions/VocabularyRefreshService.cs new file mode 100644 index 00000000..cfe4fc25 --- /dev/null +++ b/src/AgentCore.AspNetCore/Sessions/VocabularyRefreshService.cs @@ -0,0 +1,102 @@ +using AgentCore.Application.Ports; +using AgentCore.Application.State; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; + +namespace AgentCore.AspNetCore.Sessions; + +/// +/// Re-reads one vocabulary: slot's domain on its own refreshSeconds interval, for as +/// long as the host is up. +/// +/// +/// One instance per slot, following 's +/// idiom. Section 11: a refresh that fails, or that succeeds but is degenerate (K46), keeps the +/// cache's last good view and logs — already leaves the slot +/// unchanged when it throws, so this type only has to keep the loop alive and report what happened. +/// +/// The slot this instance refreshes. +/// The resolved payload path, already through scope.template. +/// The slot's vocabulary.maxValues, passed as the read's own limit. +/// The scope's wildcard sentinel to strip (K6), or . +/// The slot's vocabulary.refreshSeconds. Always greater than zero. +/// The facet read. +/// The cache this instance's reads are installed into. +/// Where the ticks from. +/// Where a failed or degenerate refresh is reported. +internal sealed class VocabularyRefreshService( + string slot, + string path, + int maxValues, + string? wildcardValue, + int refreshSeconds, + IFacetVocabularyPort port, + VocabularyCache cache, + TimeProvider timeProvider, + ILogger logger) : BackgroundService +{ + /// + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + using PeriodicTimer timer = new(TimeSpan.FromSeconds(refreshSeconds), timeProvider); + + while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false)) + { + await RefreshAsync(stoppingToken).ConfigureAwait(false); + } + } + + /// Runs one refresh: a read and an attempted install. + /// Cancels the read. + /// + /// Exposed so a test can drive one tick directly, without fighting the + /// . + /// + internal async ValueTask RefreshAsync(CancellationToken cancellationToken) + { + IReadOnlyList values; + try + { + values = await port.ReadAsync(path, maxValues, cancellationToken).ConfigureAwait(false); + } + catch (Exception fault) when (fault is not OperationCanceledException) + { + VocabularyRefreshServiceLog.RefreshFailed(logger, slot, fault); + return; + } + + try + { + cache.Replace(slot, values, maxValues, wildcardValue); + } + catch (VocabularyException degenerate) + { + VocabularyRefreshServiceLog.RefreshDegenerate(logger, slot, degenerate); + } + } +} + +/// Every line a writes. +internal static partial class VocabularyRefreshServiceLog +{ + /// A refresh's own read threw. The last good vocabulary is kept. + /// The service's own logger. + /// The slot the refresh was for. + /// The cause. + [LoggerMessage( + EventId = 1, + Level = LogLevel.Warning, + Message = "the vocabulary refresh for slot '{Slot}' failed. The last good vocabulary is kept.")] + public static partial void RefreshFailed(ILogger logger, string slot, Exception exception); + + /// A refresh's read succeeded but failed one of section 10's four boot tests (K46). + /// The service's own logger. + /// The slot the refresh was for. + /// The naming which test failed. + [LoggerMessage( + EventId = 2, + Level = LogLevel.Warning, + Message = "the vocabulary refresh for slot '{Slot}' returned a degenerate read. The last good " + + "vocabulary is kept.")] + public static partial void RefreshDegenerate(ILogger logger, string slot, Exception exception); +} diff --git a/src/AgentCore.Domain/Knowledge/PayloadPath.cs b/src/AgentCore.Domain/Knowledge/PayloadPath.cs new file mode 100644 index 00000000..695b71ec --- /dev/null +++ b/src/AgentCore.Domain/Knowledge/PayloadPath.cs @@ -0,0 +1,39 @@ +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 +{ + /// 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) + { + ArgumentNullException.ThrowIfNull(payload); + + if (path is not { Length: > 0 }) + { + return null; + } + + object? current = payload; + + foreach (var 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/PublicAPI.Unshipped.txt b/src/AgentCore.Domain/PublicAPI.Unshipped.txt index 420f9225..b5d456b1 100644 --- a/src/AgentCore.Domain/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Domain/PublicAPI.Unshipped.txt @@ -74,6 +74,7 @@ AgentCore.Domain.Knowledge.KnowledgeScope.Facets.init -> void AgentCore.Domain.Knowledge.KnowledgeScope.KnowledgeScope() -> void AgentCore.Domain.Knowledge.KnowledgeScope.Origins.get -> System.Collections.Generic.IReadOnlyDictionary! AgentCore.Domain.Knowledge.KnowledgeScope.Origins.init -> void +AgentCore.Domain.Knowledge.PayloadPath AgentCore.Domain.Sources.SourceKind AgentCore.Domain.Sources.SourceKind.Document = 0 -> AgentCore.Domain.Sources.SourceKind AgentCore.Domain.Sources.SourceKind.Url = 1 -> AgentCore.Domain.Sources.SourceKind @@ -171,6 +172,7 @@ static AgentCore.Domain.Knowledge.KnowledgeCard.operator !=(AgentCore.Domain.Kno static AgentCore.Domain.Knowledge.KnowledgeCard.operator ==(AgentCore.Domain.Knowledge.KnowledgeCard? left, AgentCore.Domain.Knowledge.KnowledgeCard? right) -> bool static AgentCore.Domain.Knowledge.KnowledgeScope.operator !=(AgentCore.Domain.Knowledge.KnowledgeScope? left, AgentCore.Domain.Knowledge.KnowledgeScope? right) -> bool static AgentCore.Domain.Knowledge.KnowledgeScope.operator ==(AgentCore.Domain.Knowledge.KnowledgeScope? left, AgentCore.Domain.Knowledge.KnowledgeScope? right) -> bool +static AgentCore.Domain.Knowledge.PayloadPath.Read(System.Collections.Generic.IReadOnlyDictionary! payload, string? path) -> object? static AgentCore.Domain.Sources.SourceReference.operator !=(AgentCore.Domain.Sources.SourceReference? left, AgentCore.Domain.Sources.SourceReference? right) -> bool static AgentCore.Domain.Sources.SourceReference.operator ==(AgentCore.Domain.Sources.SourceReference? left, AgentCore.Domain.Sources.SourceReference? right) -> bool static AgentCore.Domain.TurnResult.operator !=(AgentCore.Domain.TurnResult? left, AgentCore.Domain.TurnResult? right) -> bool diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/FieldsPointMapper.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/FieldsPointMapper.cs index edde354b..879d5e21 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/FieldsPointMapper.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/FieldsPointMapper.cs @@ -38,7 +38,7 @@ public FieldsPointMapper(KnowledgeFieldsConfiguration fields) 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 = Read(point.Payload, _fields.Authority) is long authority ? (int)authority : null, + Authority = PayloadPath.Read(point.Payload, _fields.Authority) is long authority ? (int)authority : null, Score = point.Score, ViaLink = false, @@ -50,28 +50,5 @@ public FieldsPointMapper(KnowledgeFieldsConfiguration fields) } private static string? ReadString(IReadOnlyDictionary payload, string? path) - => Read(payload, path) as string; - - /// The neutral twin of QdrantPayload.Read: one dotted-path walk, null-tolerant. - private static object? Read(IReadOnlyDictionary payload, string? path) - { - if (path is not { Length: > 0 }) - { - return null; - } - - object? current = null; - var fields = payload; - foreach (var part in path.Split('.')) - { - if (fields is null || !fields.TryGetValue(part, out current)) - { - return null; - } - - fields = current as IReadOnlyDictionary; - } - - return current; - } + => 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 f49b6271..4480e14e 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/IQdrantSearchChannel.cs @@ -38,4 +38,13 @@ Task> RetrieveAsync( /// The points that matched. An empty result is not an error. Task> ScrollAsync( string collection, Filter filter, uint limit, CancellationToken cancellationToken); + + /// Reads the distinct values stored at one payload path. + /// The collection. + /// The payload path. + /// The most values to return. + /// Cancels the call. + /// The distinct values, in the order Qdrant returns them. + Task> FacetAsync( + string collection, string key, ulong limit, CancellationToken cancellationToken); } diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs index 6e22c6de..f12cdc51 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs @@ -1,3 +1,4 @@ +using AgentCore.Application.Configuration.Parsing; using AgentCore.Application.Configuration.Schema; using AgentCore.Application.Knowledge; using AgentCore.Application.Ports; @@ -12,12 +13,13 @@ namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; /// /// The whole knowledge base over one Qdrant collection. /// -internal sealed class QdrantKnowledgeStore : IKnowledgeRetrievalPort, IDisposable +internal sealed class QdrantKnowledgeStore : IKnowledgeRetrievalPort, IFacetVocabularyPort, IDisposable { private readonly IQdrantSearchChannel _channel; private readonly IEmbeddingGenerator> _embeddings; private readonly QdrantKnowledgeStoreOptions _options; private readonly IKnowledgePointMapper _mapper; + private readonly ScopeTemplate? _scopeTemplate; /// Binds one channel, one embedder and one collection. public QdrantKnowledgeStore( @@ -32,6 +34,7 @@ public QdrantKnowledgeStore( _channel = channel; _embeddings = embeddings; _options = options; + _scopeTemplate = 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. @@ -150,6 +153,22 @@ public async ValueTask> SearchAsync( return cards; } + /// + /// + /// is resolved verbatim: the caller has already applied + /// scope.template, so this never prefixes or rewrites it. + /// + public async ValueTask> ReadAsync( + string path, int limit, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(path); + ArgumentOutOfRangeException.ThrowIfNegative(limit); + + return await _channel + .FacetAsync(_options.Collection, path, (ulong)limit, cancellationToken) + .ConfigureAwait(false); + } + private SearchQuery BuildQuery(string query, ReadOnlyMemory vector, KnowledgeScope? scope) { var scopeFilter = new Filter(); @@ -324,12 +343,12 @@ private bool InScope(MapField payload, KnowledgeScope? scope) => /// not at startup: a deployment whose agents never scope legitimately names no template. /// private string ScopePath(string facet) - => _options.ScopeTemplate is { Length: > 0 } template - ? template.Replace("{key}", facet, StringComparison.Ordinal) + => _scopeTemplate is { } template + ? template.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. There is no " - + "default. Write scope.template, such as '{key}' for flat facets."); + + "unset, so AgentCore does not know what payload path that key becomes. " + + ScopeTemplate.WriteOneAdvice); /// Mirrors Qdrant keyword matching, where a list facet matches when any element does. private static bool Holds(Value? facet, IReadOnlyList wanted) => facet switch diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs index f891f41b..564c6dd5 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantSearchChannel.cs @@ -72,6 +72,19 @@ public async Task> ScrollAsync( return response.Result; } + /// + public async Task> FacetAsync( + string collection, string key, ulong limit, CancellationToken cancellationToken) + { + // exact: true always. Measured equal to exact: false on 2- and 8-segment collections + // (P4); the guarantee is the caller's and the measured cost was 6 ms. + var response = await RunAsync( + () => _client.FacetAsync(collection, key, limit: limit, exact: true, cancellationToken: cancellationToken), + cancellationToken).ConfigureAwait(false); + + return [.. response.Hits.Select(hit => hit.Value.StringValue)]; + } + /// /// Runs one gRPC call and converts a client-side cancellation into . /// diff --git a/tests/AgentCore.Application.Tests/Compilation/ClarificationWiringBindingTests.cs b/tests/AgentCore.Application.Tests/Compilation/ClarificationWiringBindingTests.cs new file mode 100644 index 00000000..89786d50 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Compilation/ClarificationWiringBindingTests.cs @@ -0,0 +1,222 @@ +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Runtime; +using AgentCore.Domain.Knowledge; +using AgentCore.TestSupport; +using Microsoft.Agents.AI; +using Xunit; + +namespace AgentCore.Application.Tests.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. +/// +/// +/// KnowledgeProbeTests hand-builds its ResolvedKnowledge and so proves only that the +/// probe reads what it is given. These tests compile a real document, so a compiler that composed +/// the block and then handed the probe an unwired one fails here — where it would otherwise ship +/// green and degrade every deployment's probe to the "holds nothing" notice. +/// +public sealed class ClarificationWiringBindingTests +{ + private const string ModelDescription = "The model, as printed on the machine."; + + private const string WiredYaml = + """ + apiVersion: agentcore/v1 + name: clarification-wiring + state: + model: + type: string + writer: extractor + description: "The model, as printed on the machine." + audience: + type: string + writer: const + value: everyone + enum: [everyone] + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [model, audience] + wildcard: { value: "*", facets: [model] } + ambiguity: { maxCandidates: 3, maxAsks: 2 } + agents: + items: + - id: only + instructions: "I read the bank" + knowledge: { mode: tool, scoped: true } + """; + + private const string TwoAgentYaml = + """ + apiVersion: agentcore/v1 + name: clarification-wiring-two-agents + state: + model: + type: string + writer: extractor + description: "The model, as printed on the machine." + audience: + type: string + writer: const + value: everyone + enum: [everyone] + policy: + initial: greeting + stages: + - { id: greeting, agent: greeter } + - { id: answering, agent: reader } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [model, audience] + wildcard: { value: "*", facets: [model] } + ambiguity: { maxCandidates: 3, maxAsks: 2 } + agents: + items: + - { id: greeter, instructions: "I say hello" } + - { id: reader, instructions: "I read the bank", knowledge: { mode: tool, scoped: true } } + """; + + [Fact] + public void EveryAgentInOneDocument_SharesTheOneClarificationProvider() + { + // The provider's three fields are the document's wiring and it keeps nothing per agent, so a + // second instance would be a second copy of the same thing. Channel 1 is bound to agents that + // declare no knowledge: block of their own, so this is every agent in the document, not just + // the ones that search. + using SequencedChatClient reply = new("hello there."); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(TwoAgentYaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = new ScopedFakePort() }); + + var greeter = Assert.Single(Providers(compiled.Agents["greeter"]).OfType()); + var reader = Assert.Single(Providers(compiled.Agents["reader"]).OfType()); + + Assert.Same(greeter, reader); + } + + [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(); + using var clarifications = TurnAmbientsTestScope.WithClarifications(new Clarifications()); + using var scope = KnowledgeScopeScope.Open(Scope(model: "*", audience: "everyone")); + + var note = await SearchAsync(CompileTheSearchProvider(port), "belt slipping"); + + 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(); + using var clarifications = TurnAmbientsTestScope.WithClarifications(new Clarifications()); + using var scope = KnowledgeScopeScope.Open(Scope(model: "*", audience: "everyone")); + + var note = await SearchAsync(CompileTheSearchProvider(port), "belt slipping"); + + Assert.Contains(ModelDescription, note, StringComparison.Ordinal); + Assert.DoesNotContain("known: model ", note, StringComparison.Ordinal); + } + + private static TextSearchProvider CompileTheSearchProvider(IKnowledgeRetrievalPort port) + { + using SequencedChatClient reply = new("hello there."); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(WiredYaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) { Knowledge = port }); + + return Assert.Single(Providers(compiled.Agents["only"]).OfType()); + } + + private static IEnumerable Providers(AIAgent agent) + { + var inner = agent.GetService(); + Assert.NotNull(inner); + + return inner.AIContextProviders ?? []; + } + + private static KnowledgeScope Scope(string model, string audience) + => new() + { + Facets = new Dictionary(StringComparer.Ordinal) + { + ["model"] = model, + ["audience"] = audience, + }, + }; + + /// The one notice the bound search returned, as text. + private static async Task SearchAsync(TextSearchProvider provider, string query) + => Assert.Single( + await TextSearchProviderInternals.SearchAsync( + provider, query, TestContext.Current.CancellationToken).ConfigureAwait(false)).Text; + + /// + /// 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, CancellationToken cancellationToken = default) + { + Calls++; + + var facets = KnowledgeScopeScope.Current?.Facets; + if (facets is null || facets.ContainsKey("model")) + { + return new([]); + } + + return new([Card("a", "e33"), Card("b", "f63")]); + } + + private static KnowledgeCard Card(string id, string model) + => new() + { + 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/AgentKnowledgeTests.cs b/tests/AgentCore.Application.Tests/Configuration/AgentKnowledgeTests.cs index 7518363b..f9ff3c3e 100644 --- a/tests/AgentCore.Application.Tests/Configuration/AgentKnowledgeTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/AgentKnowledgeTests.cs @@ -161,6 +161,20 @@ public void AllScoped_AgentInheritsUnscopedFromDefaultsWithNoOwnBlock_IsFalse() Assert.False(AgentKnowledge.AllScoped(section)); } + [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 TheShippedSchema_CapsLimitAtTheSameValueAsTheConstant() { diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs index bcfb1cca..650d4aac 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationBinderTests.cs @@ -1,4 +1,5 @@ using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; using Xunit; namespace AgentCore.Application.Tests.Configuration; @@ -257,4 +258,179 @@ public void Bind_KnowledgeScopeWildcardAndFromState_ReadsBoth() Assert.Equal(["brand", "applies_to"], scope.Wildcard.Facets); Assert.Equal(["brand", "applies_to"], scope.FromState); } + + [Fact] + public void Bind_VocabularySlot_ReadsFromAndDefaults() + { + const string Document = """ + apiVersion: agentcore/v1 + name: doc + state: + applies_to: { type: string, writer: extractor, vocabulary: { from: knowledge } } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + """; + + var configuration = ConfigurationLoader.LoadYaml(Document); + var vocabulary = configuration.State["applies_to"].Vocabulary; + + Assert.NotNull(vocabulary); + Assert.Equal("knowledge", vocabulary!.From); + Assert.Equal(SlotVocabularyConfiguration.DefaultLinker, vocabulary.Linker); + Assert.Equal(SlotVocabularyConfiguration.DefaultRefreshSeconds, vocabulary.RefreshSeconds); + Assert.Equal(SlotVocabularyConfiguration.DefaultMaxValues, vocabulary.MaxValues); + Assert.False(vocabulary.AssumeNormalized); + } + + [Fact] + public void Bind_VocabularySlot_ReadsEveryField() + { + const string Document = """ + apiVersion: agentcore/v1 + name: doc + state: + applies_to: + type: string + writer: extractor + vocabulary: { from: knowledge, linker: exact, refreshSeconds: 900, maxValues: 500, assumeNormalized: true } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + """; + + var configuration = ConfigurationLoader.LoadYaml(Document); + var vocabulary = configuration.State["applies_to"].Vocabulary!; + + Assert.Equal("knowledge", vocabulary.From); + Assert.Equal("exact", vocabulary.Linker); + Assert.Equal(900, vocabulary.RefreshSeconds); + Assert.Equal(500, vocabulary.MaxValues); + Assert.True(vocabulary.AssumeNormalized); + } + + /// from: is the one member the design allows, so the schema declares it as an enum of one. + [Fact] + public void Bind_VocabularyFromOtherThanKnowledge_FailsCheckOne() + { + const string Document = """ + apiVersion: agentcore/v1 + name: doc + state: + applies_to: { type: string, writer: extractor, vocabulary: { from: somewhere_else } } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + """; + + var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(Document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/state/applies_to/vocabulary/from"); + } + + /// additionalProperties: false on the nested object, not only on stateSlot itself. + [Fact] + public void Bind_AnUnknownVocabularyKey_FailsCheckOne() + { + const string Document = """ + apiVersion: agentcore/v1 + name: doc + state: + applies_to: { type: string, writer: extractor, vocabulary: { from: knowledge, bogus: 1 } } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + """; + + var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(Document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + } + + [Fact] + public void Bind_AmbiguityBlock_ReadsDefaults() + { + const string Document = """ + apiVersion: agentcore/v1 + name: doc + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + ambiguity: {} + """; + + var configuration = ConfigurationLoader.LoadYaml(Document); + var 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); + } + + [Fact] + public void Bind_AmbiguityBlock_ReadsEveryField() + { + const string Document = """ + apiVersion: agentcore/v1 + name: doc + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + ambiguity: { maxCandidates: 4, maxAsks: 1, probeDeadlineSeconds: 3, probeWaitMarginSeconds: 2 } + """; + + var configuration = ConfigurationLoader.LoadYaml(Document); + var 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); + } + + [Fact] + public void Bind_AnUnknownAmbiguityKey_FailsCheckOne() + { + const string Document = """ + apiVersion: agentcore/v1 + name: doc + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + ambiguity: { bogus: 1 } + """; + + var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(Document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs index 01dc67aa..d659a453 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs @@ -346,7 +346,9 @@ private static AgentCoreConfiguration Scoped( IReadOnlyList fromState, KnowledgeWildcardConfiguration? wildcard, IDictionary state, - ExtractorConfiguration? extractor = null) => new() + ExtractorConfiguration? extractor = null, + KnowledgeAmbiguityConfiguration? ambiguity = null, + string? mapper = null) => new() { ApiVersion = "agentcore/v1", Name = "doc", @@ -354,17 +356,23 @@ private static AgentCoreConfiguration Scoped( 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() { Kind = "qdrant", Collection = "kb", Fields = new() { Body = "text" }, + Mapper = mapper, Scope = new() { Template = "facets.{key}", Wildcard = wildcard, FromState = fromState, }, + Ambiguity = ambiguity, }, }, }; @@ -376,6 +384,15 @@ private static AgentCoreConfiguration Scoped( EnumValues = [JsonValue.Create("f63")!], }; + private static StateSlotConfiguration VocabSlot(SlotVocabularyConfiguration? vocabulary = null) => new() + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + Vocabulary = vocabulary ?? new SlotVocabularyConfiguration { From = "knowledge" }, + }; + + private static KnowledgeAmbiguityConfiguration AnAmbiguity() => new(); + private static readonly KnowledgeWildcardConfiguration Star = new() { Value = "*", Facets = ["applies_to"] }; @@ -483,19 +500,43 @@ public void Evaluate_FromStateWithNoExtractor_Fails() [Fact] public void Evaluate_FromStateNameNotInWildcardFacets_Fails() { - var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["other_facet"] }; + // 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"] }; var result = ConfigurationValidator.EvaluateStructure( Scoped( - ["applies_to"], + ["applies_to", "brand"], wildcard, - new Dictionary { ["applies_to"] = FacetSlot() }, + new Dictionary + { + ["applies_to"] = FacetSlot(), + ["brand"] = FacetSlot(), + }, AnExtractor())); 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_WildcardFacetNotInFromState_Fails() + { + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "other_facet"] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + wildcard, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor())); + + 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_FacetWildcardValueIsWhitespace_Fails() { @@ -507,6 +548,17 @@ public void Evaluate_FacetWildcardValueIsWhitespace_Fails() 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())); + + Assert.Empty(result.Errors); + } + [Fact] public void Evaluate_FacetWildcardDeclaresNoFacets_Fails() { @@ -518,6 +570,453 @@ public void Evaluate_FacetWildcardDeclaresNoFacets_Fails() Assert.Single(result.Errors, e => e.Pointer == "/providers/knowledge/scope/wildcard/facets"); } + [Fact] + public void Evaluate_FacetSlotDeclaresVocabularyInsteadOfEnum_PassesTheEnumRow() + { + var slot = FacetSlot() with { EnumValues = null, Vocabulary = new SlotVocabularyConfiguration { From = "knowledge" } }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + Assert.Empty(result.Errors); + } + + // --------------------------------------------------------------------------------------------- + // Check 2, vocabulary and ambiguity: section 10 of the ambiguity-and-vocabulary 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-or-vocabulary 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_SlotDeclaresBothEnumAndVocabulary_Fails() + { + var slot = VocabSlot() with { EnumValues = [JsonValue.Create("f63")!] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + var error = Assert.Single(result.Errors); + Assert.Equal("/state/applies_to/vocabulary", error.Pointer); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } + + /// + /// A writer: const slot can never legitimately sit in fromState (fromState's + /// per-facet check requires writer: extractor), so a slot exercising this row also, + /// unavoidably, trips row 3 (vocabulary.from on a slot fromState does not name). The pair is + /// asserted explicitly rather than isolated away. + /// + [Fact] + public void Evaluate_SlotDeclaresBothValueAndVocabulary_Fails() + { + var slot = VocabSlot() with { Writer = StateWriter.Const, Value = JsonValue.Create("f63") }; + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["brand"] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["brand"], + wildcard, + new Dictionary + { + ["applies_to"] = slot, + ["brand"] = FacetSlot(), + }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + Assert.Equal(2, result.Errors.Count); + Assert.Contains(result.Errors, e => e.Pointer == "/state/applies_to/value"); + Assert.Contains(result.Errors, e => e.Pointer == "/state/applies_to/vocabulary/from"); + } + + [Fact] + public void Evaluate_VocabularySlotAbsentFromFromState_Fails() + { + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["brand"] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["brand"], + wildcard, + new Dictionary + { + ["applies_to"] = VocabSlot(), + ["brand"] = FacetSlot(), + }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + var error = Assert.Single(result.Errors); + Assert.Equal("/state/applies_to/vocabulary/from", error.Pointer); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void Evaluate_VocabularyMaxValuesBelowTwo_Fails() + { + var slot = VocabSlot(new SlotVocabularyConfiguration { From = "knowledge", MaxValues = 1 }); + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + var error = Assert.Single(result.Errors); + Assert.Equal("/state/applies_to/vocabulary/maxValues", error.Pointer); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void Evaluate_VocabularyRefreshSecondsNegative_Fails() + { + var slot = VocabSlot(new SlotVocabularyConfiguration { From = "knowledge", RefreshSeconds = -5 }); + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + var error = Assert.Single(result.Errors); + Assert.Equal("/state/applies_to/vocabulary/refreshSeconds", error.Pointer); + Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void Evaluate_VocabularyWithNoAmbiguity_Fails() + { + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = VocabSlot() }, + AnExtractor())); + + var error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity", error.Pointer); + } + + [Fact] + public void Evaluate_AmbiguityWithNoWildcard_Fails() + { + var result = ConfigurationValidator.EvaluateStructure( + Scoped([], wildcard: null, new Dictionary(), ambiguity: AnAmbiguity())); + + var error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity", error.Pointer); + } + + [Fact] + public void Evaluate_AmbiguityMaxCandidatesBelowTwo_Fails() + { + var ambiguity = new KnowledgeAmbiguityConfiguration { MaxCandidates = 1 }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity: ambiguity)); + + var 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 }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity: ambiguity)); + + var 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 }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity: ambiguity)); + + Assert.Empty(result.Errors); + } + + [Fact] + public void Evaluate_AmbiguityProbeDeadlineSecondsBelowOne_Fails() + { + var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 0 }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity: ambiguity)); + + var 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 }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity: ambiguity)); + + var error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity/probeWaitMarginSeconds", error.Pointer); + } + + [Fact] + public void Evaluate_VocabularyWithCustomMapper_Fails() + { + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = VocabSlot() }, + AnExtractor(), + ambiguity: AnAmbiguity(), + mapper: "custom-mapper")); + + var error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/mapper", error.Pointer); + } + + [Fact] + public void Evaluate_AmbiguityWithCustomMapperAndNoVocabulary_Fails() + { + // The probe reads Extras, and nothing about vocabulary puts it there. A document that declares + // ambiguity without vocabulary must still be refused a mapper that leaves Extras empty. + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to", "brand"], + wildcard, + new Dictionary + { + ["applies_to"] = FacetSlot(), + ["brand"] = FacetSlot(), + }, + AnExtractor(), + ambiguity: AnAmbiguity(), + mapper: "custom-mapper")); + + var 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 call site with no pointer. + var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 3_000_000 }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity: ambiguity)); + + var 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 }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity: ambiguity)); + + var error = Assert.Single(result.Errors); + Assert.Equal("/providers/knowledge/ambiguity/probeWaitMarginSeconds", error.Pointer); + } + + [Fact] + public void Evaluate_VocabularyRefreshSecondsAboveTheTimerCeiling_Fails() + { + // PeriodicTimer throws above uint.MaxValue - 1 milliseconds, inside BootAsync. + var slot = VocabSlot(new SlotVocabularyConfiguration { From = "knowledge", RefreshSeconds = 86_400_000 }); + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + var error = Assert.Single(result.Errors); + Assert.Equal("/state/applies_to/vocabulary/refreshSeconds", error.Pointer); + Assert.Equal(ConfigurationCheck.ValueRange, error.Check); + } + + [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())); + + Assert.Empty(result.Errors); + var warning = Assert.Single(result.Warnings); + Assert.Equal("/providers/knowledge/ambiguity", warning.Pointer); + } + + [Fact] + public void Evaluate_AmbiguityWithSingleFacetFromState_Warns() + { + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + Assert.Empty(result.Errors); + var warning = Assert.Single(result.Warnings); + Assert.Equal("/providers/knowledge/ambiguity", warning.Pointer); + } + + [Fact] + public void Evaluate_AmbiguityWithTwoFacetsFromState_DoesNotWarn() + { + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to", "brand"], + wildcard, + new Dictionary + { + ["applies_to"] = FacetSlot(), + ["brand"] = FacetSlot(), + }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + Assert.Empty(result.Errors); + Assert.Empty(result.Warnings); + } + + [Fact] + public void Evaluate_AmbiguityOnAGraphDocument_Warns() + { + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; + + var configuration = Scoped( + ["applies_to", "brand"], + wildcard, + new Dictionary + { + ["applies_to"] = FacetSlot(), + ["brand"] = FacetSlot(), + }, + AnExtractor(), + ambiguity: AnAmbiguity()) + with { Graph = new GraphConfiguration() }; + + var result = ConfigurationValidator.EvaluateStructure(configuration); + + Assert.Empty(result.Errors); + var warning = Assert.Single(result.Warnings); + Assert.Equal("/providers/knowledge/ambiguity", warning.Pointer); + } + + /// + /// Same two-facet base as , minus + /// graph: — the direct control for it, and incidentally the same witness that proves + /// the two-facet count keeps the single-facet warning (K33) silent too. + /// + [Fact] + public void Evaluate_AmbiguityOnANonGraphDocument_DoesNotWarnAboutGraph() + { + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; + + var result = ConfigurationValidator.EvaluateStructure( + Scoped( + ["applies_to", "brand"], + wildcard, + new Dictionary + { + ["applies_to"] = FacetSlot(), + ["brand"] = FacetSlot(), + }, + AnExtractor(), + ambiguity: AnAmbiguity())); + + Assert.Empty(result.Errors); + Assert.Empty(result.Warnings); + } + + [Fact] + public void Evaluate_NoVocabularyAndNoAmbiguity_BindsNullAndAddsNothing() + { + var configuration = ConfigurationLoader.LoadYaml(ExampleDocument.Yaml); + + Assert.All(configuration.State.Values, slot => Assert.Null(slot.Vocabulary)); + Assert.Null(configuration.Providers?.Knowledge?.Ambiguity); + + var result = ConfigurationValidator.Evaluate(configuration); + + Assert.Empty(result.Errors); + Assert.Empty(result.Warnings); + } + // --------------------------------------------------------------------------------------------- // Check 3: one writer for each slot. // --------------------------------------------------------------------------------------------- @@ -1219,6 +1718,59 @@ public void ValidateToolReferences_AnIdOnlyDiscoveryServes_Passes() Assert.Null(exception); } + [Fact] + public void ValidateLinkerNames_ANameNothingRegistered_FailsNamingItAndThePointer() + { + const string document = """ + apiVersion: agentcore/v1 + name: broken-linker + state: + applies_to: { type: string, writer: extractor, vocabulary: { from: knowledge, linker: bogus } } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + """; + + var configuration = ConfigurationLoader.LoadYaml(document); + var registered = new HashSet(["exact"], StringComparer.Ordinal); + + var failure = Assert.Throws( + () => ConfigurationValidator.ValidateLinkerNames(configuration, registered)); + + var error = Assert.Single(failure.Errors); + Assert.Equal("/state/applies_to/vocabulary/linker", error.Pointer); + Assert.Equal( + "the slot 'applies_to' declares vocabulary.linker: 'bogus', which nothing registered. " + + "Register it with UseStateValueLinkers, or use 'exact'.", + error.Message); + Assert.Equal(ConfigurationCheck.ReferenceResolution, error.Check); + } + + [Fact] + public void ValidateLinkerNames_ARegisteredName_DoesNotThrow() + { + const string document = """ + apiVersion: agentcore/v1 + name: fine-linker + state: + applies_to: { type: string, writer: extractor, vocabulary: { from: knowledge, linker: exact } } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + """; + + var configuration = ConfigurationLoader.LoadYaml(document); + var registered = new HashSet(["exact"], StringComparer.Ordinal); + + var exception = Record.Exception(() => ConfigurationValidator.ValidateLinkerNames(configuration, registered)); + + Assert.Null(exception); + } + [Fact] public void ValidateSkillReferences_ANameTheFolderDoesNotServe_FailsNamingItAndWhatIsServed() { @@ -1350,7 +1902,7 @@ private static string WideDocument(int slots) text.AppendLine("state:"); for (var index = 0; index < slots; index++) { - text.AppendLine($" s{index}: {{ type: boolean, default: false, writer: extractor }}"); + text.AppendLine(System.Globalization.CultureInfo.InvariantCulture, $" s{index}: {{ type: boolean, default: false, writer: extractor }}"); } text.AppendLine("guards:"); @@ -1358,7 +1910,7 @@ private static string WideDocument(int slots) text.Append(" second: { and: [ { \"!\": { var: s0 } }"); for (var index = 1; index < slots; index++) { - text.Append($", {{ var: s{index} }}"); + text.Append(System.Globalization.CultureInfo.InvariantCulture, $", {{ var: s{index} }}"); } text.AppendLine(" ] }"); diff --git a/tests/AgentCore.Application.Tests/Knowledge/Fakes/StubKnowledgePort.cs b/tests/AgentCore.Application.Tests/Knowledge/Fakes/StubKnowledgePort.cs index 26f2fbfa..0cfadd8a 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/Fakes/StubKnowledgePort.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/Fakes/StubKnowledgePort.cs @@ -27,12 +27,17 @@ public StubKnowledgePort(IReadOnlyList cards) /// public KnowledgeScope? ScopeAtTheStore { get; private set; } + /// Gets the ambient on the flow when the last search arrived. + /// Read at the same point as , for the same reason. + public Clarifications? ClarificationsAtTheStore { get; private set; } + public ValueTask> SearchAsync( string query, CancellationToken cancellationToken = default) { LastQuery = query; ScopeAtTheStore = KnowledgeScopeScope.Current; + ClarificationsAtTheStore = TurnAmbients.Current?.Clarifications; Calls++; return ValueTask.FromResult(_cards); } diff --git a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProbeTests.cs b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProbeTests.cs new file mode 100644 index 00000000..96ef04aa --- /dev/null +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProbeTests.cs @@ -0,0 +1,1221 @@ +using AgentCore.Application.Configuration.Parsing; +using System.Diagnostics; +using System.Reflection; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Knowledge; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.Tests.Runtime; +using AgentCore.Domain.Knowledge; +using AgentCore.TestSupport; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +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 KnowledgeProviderFactory's own search delegate directly, the same way +/// KnowledgeProviderFactoryTests does, rather than through CallSession: the probe reads +/// only the ambient (, , +/// ) and the resolved knowledge: block, so opening exactly those by +/// hand proves the same mechanism a real call would exercise, at a fraction of the setup. The +/// genuinely two-turn and delegation-shaped cases live in CallSessionProbeTests. +/// +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. + + [Fact] + public async Task Step1_MainSearchReturnedCards_TheProbeNeverRuns() + { + var port = new ProbeFakePort((_, _) => Task.FromResult>([Card("a")])); + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + 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>([])); + using var clarifications = OpenClarifications(); + + var results = await InvokeSearchAsync( + Provider(port, Resolved(["applies_to"], scoped: false)), "e33"); + + 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>([])); + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var plain = new ResolvedKnowledge(KnowledgeMode.Tool, 5, Citations: false, Scoped: true); + var results = await InvokeSearchAsync(Provider(port, plain), "e33"); + + Assert.Contains(results, r => r.Text.Contains("holds nothing", StringComparison.Ordinal)); + Assert.Equal(1, port.Calls); + } + + // §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>([])); + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to")); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + 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>([])); + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("brand", "applies_to")); + + var knowledge = Resolved(["brand", "applies_to"], ambiguity: new KnowledgeAmbiguityConfiguration { MaxAsks = 0 }); + var results = await InvokeSearchAsync(Provider(port, knowledge), "e33"); + + 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")])); + + var clarificationsObject = new Clarifications(); + clarificationsObject.Update("brand", s => s.ProbeAsks = 2); + using var clarifications = OpenClarifications(clarificationsObject); + using var scope = KnowledgeScopeScope.Open(FullScope("brand", "applies_to")); + + var knowledge = Resolved(["brand", "applies_to"]); + var results = await InvokeSearchAsync(Provider(port, knowledge), "e33"); + + 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 Step3_FacetChannel1AlreadyAskedThisTurn_IsSkipped() + { + // K41: one slot is asked by at most one channel per turn. brand is skipped, so applies_to -- + // the only other droppable facet -- is what the probe's second search actually drops. + var port = new ProbeFakePort((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + + var clarificationsObject = new Clarifications(); + clarificationsObject.Update("brand", s => s.AskedThisTurn = true); + using var clarifications = OpenClarifications(clarificationsObject); + using var scope = KnowledgeScopeScope.Open(FullScope("brand", "applies_to")); + + var knowledge = Resolved(["brand", "applies_to"]); + var results = await InvokeSearchAsync(Provider(port, knowledge), "e33"); + + Assert.Contains(results, r => r.Text.Contains("ct900", StringComparison.Ordinal)); + Assert.Equal(0, 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")])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "brand")); + + // 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"); + + Assert.Contains(results, r => r.Text.Contains("ct900", StringComparison.Ordinal)); + } + + // §8 steps 5-6: reading candidates and choosing the message. + + [Fact] + public async Task Steps5And6_FindsCandidates_SetsThePendingListAndEmitsTheNote() + { + 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(); + using var clarifications = OpenClarifications(clarificationsObject); + using var carries = TurnAmbientsTestScope.WithCarriesHistory(true); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var knowledge = Resolved(["applies_to"], slotDescriptions: Descriptions(("applies_to", Description))); + var results = await InvokeSearchAsync(Provider(port, knowledge), "e33"); + + Assert.Equal( + ClarificationText.Note(Description, ["ct900", "ct900ent"], KnowledgeAmbiguityConfiguration.DefaultMaxCandidates), + Assert.Single(results).Text); + + var snapshot = clarificationsObject.Read("applies_to"); + Assert.Equal(["ct900", "ct900ent"], snapshot.Pending); + 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"])])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + var 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)])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var results = await InvokeSearchAsync( + Provider(port, Resolved(["applies_to"], template: template)), "e33"); + + 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")])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + var 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")])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var results = await InvokeSearchAsync( + Provider(port, Resolved(["applies_to"], slotDescriptions: Descriptions(("applies_to", Description)))), + "e33"); + + 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))])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var knowledge = Resolved( + ["applies_to"], ambiguity: new KnowledgeAmbiguityConfiguration { MaxCandidates = 6 }); + var results = await InvokeSearchAsync(Provider(port, knowledge), "e33"); + + var text = Assert.Single(results).Text; + Assert.DoesNotContain("holds nothing", text, StringComparison.Ordinal); + foreach (var 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))); + using var clarifications = OpenClarifications(clarificationsObject); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); + + // probeAsks still advances -- the slot was tried, it just had nothing new to say. + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } + + [Fact] + public async Task ZeroCandidatesFound_EmitsHoldsNothing() + { + var port = new ProbeFakePort((_, _) => Task.FromResult>([])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); + } + + // K39: a graph document's probe still speaks, but must not record what it named. + + [Fact] + public async Task K39_AGraphDocumentsProbe_EmitsItsNote_AndRecordsNoLastNamed() + { + var port = new ProbeFakePort((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + + var clarificationsObject = new Clarifications(); + using var clarifications = OpenClarifications(clarificationsObject); + using var carries = TurnAmbientsTestScope.WithCarriesHistory(false); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + Assert.Contains("ct900", Assert.Single(results).Text, StringComparison.Ordinal); + + var snapshot = clarificationsObject.Read("applies_to"); + // The pending list is still set: a later turn on the SAME graph row's session may still get + // an answer through the linker. Only the RECORD of what was named is withheld (K21's + // tie-break rests on the caller having heard the list, which AgentCore cannot know here). + Assert.Equal(["ct900"], snapshot.Pending); + Assert.Equal(Clarifications.LastNamedKind.None, snapshot.LastNamed.Kind); + } + + // K42: no holder, no probe -- but the notice is still owed to a scoped run. + + [Fact] + public async Task K42_NoHolderOnTheAmbient_TheProbeDoesNotSearch_ButStillEmitsTheNotice() + { + var port = new ProbeFakePort((_, _) => Task.FromResult>([])); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + // No Clarifications opened on the ambient at all -- the K42 strip inside a nested tool call. + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + Assert.Contains("holds nothing", Assert.Single(results).Text, StringComparison.Ordinal); + Assert.Equal(1, port.Calls); + } + + [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 ambient, + // leaving the outer call id in place. + var port = new ProbeFakePort((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + + var clarificationsObject = new Clarifications(); + var knowledge = Resolved(["applies_to"]); + var provider = Provider(port, knowledge); + + using (OpenClarifications(clarificationsObject)) + using (KnowledgeScopeScope.Open(FullScope("applies_to", "other"))) + { + IReadOnlyList nested; + using (TurnAmbients.Amend(a => a with { Clarifications = null })) + { + nested = await InvokeSearchAsync(provider, "the sub-agent's own question"); + } + + 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); + + var callers = await InvokeSearchAsync(provider, "the caller's own question"); + + Assert.Contains("ct900", Assert.Single(callers).Text, StringComparison.Ordinal); + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } + } + + // K25: every notice this design emits carries the reserved source name, and none is citable. + + [Fact] + public async Task EveryOutcome_CarriesTheReservedSourceName() + { + var holdsNothing = new ProbeFakePort((_, _) => Task.FromResult>([])); + using (OpenClarifications()) + using (KnowledgeScopeScope.Open(FullScope("applies_to", "other"))) + { + var results = await InvokeSearchAsync(Provider(holdsNothing, Resolved(["applies_to"])), "e33"); + 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")])); + using (OpenClarifications()) + using (KnowledgeScopeScope.Open(FullScope("applies_to", "other"))) + { + var results = await InvokeSearchAsync(Provider(named, Resolved(["applies_to"])), "e33"); + Assert.All(results, r => Assert.Equal(KnowledgeNotices.SourceName, r.SourceName)); + } + } + + [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(); + + using (OpenClarifications()) + using (KnowledgeScopeScope.Open(FullScope("applies_to", "other"))) + using (TurnAmbientsTestScope.WithSources(sources)) + using (TurnAmbientsTestScope.WithOuterCall("call-1")) + { + await InvokeSearchAsync(provider, "e33"); + } + + Assert.Empty(sources.TakeFor("call-1")); + } + + // K32: the probe's own try, its own budget, its own log events. + + [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(); + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var provider = KnowledgeProviderFactory.Create( + port, Resolved(["applies_to"]), "agent-under-test", new SourceLocatorCitationFormatter(), loggers); + var results = await InvokeSearchAsync(provider, "e33"); + + 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)); + } + + [Fact] + public async Task Probe_SecondSearchTimesOut_IsTreatedAsAFailure_NeverAsUnreachable() + { + var port = new ProbeFakePort(async (facets, cancellationToken) => + { + if (facets.ContainsKey("applies_to")) + { + return []; + } + + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + throw new UnreachableException(); + }); + + var clarificationsObject = new Clarifications(); + using var clarifications = OpenClarifications(clarificationsObject); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var knowledge = Resolved( + ["applies_to"], + ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 1, ProbeWaitMarginSeconds = 1 }); + var results = await InvokeSearchAsync(Provider(port, knowledge), "e33"); + + 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); + } + + // K43: at most once per turn -- the latch, the replay, and cancellation. + + [Fact] + public async Task K43_ThreeSearchCallsInOneTurn_RunOneProbe_AndIncrementOnce() + { + var port = new ProbeFakePort((facets, _) => Task.FromResult>( + facets.ContainsKey("applies_to") ? [] : [CardWithFacet("a", "applies_to", "ct900")])); + + var clarificationsObject = new Clarifications(); + var provider = Provider(port, Resolved(["applies_to"])); + + using (OpenClarifications(clarificationsObject)) + using (KnowledgeScopeScope.Open(FullScope("applies_to", "other"))) + { + var first = await InvokeSearchAsync(provider, "e33"); + var second = await InvokeSearchAsync(provider, "e33 again"); + var third = await InvokeSearchAsync(provider, "e33 once more"); + + 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 calls, one probe. + Assert.Equal(4, port.Calls); + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } + + [Fact] + public async Task K43_TwoCalls_TheFirstEmittedHoldsNothing_TheSecondReplaysTheSameBytes() + { + var port = new ProbeFakePort((_, _) => Task.FromResult>([])); + var provider = Provider(port, Resolved(["applies_to"])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var first = await InvokeSearchAsync(provider, "e33"); + var second = await InvokeSearchAsync(provider, "e33 again"); + + // InvokeSearchAsync itself materialises a fresh list with ToList(), so the replay proof is on + // the element the two lists share, not on the wrapper InvokeSearchAsync just allocated. + Assert.Same(first[0], second[0]); + } + + [Fact] + public async Task K43_TwoCalls_TheFirstProbeThrows_TheSecondReplaysHoldsNothing() + { + var thrown = 0; + var port = new ProbeFakePort((facets, _) => + { + if (facets.ContainsKey("applies_to")) + { + return Task.FromResult>([]); + } + + thrown++; + throw new InvalidOperationException("down"); + }); + + var provider = Provider(port, Resolved(["applies_to"])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var first = await InvokeSearchAsync(provider, "e33"); + var second = await InvokeSearchAsync(provider, "e33 again"); + + Assert.Equal(1, thrown); + Assert.Same(first[0], second[0]); + Assert.Contains("holds nothing", first[0].Text, StringComparison.Ordinal); + } + + [Fact] + public async Task K43_ACancelledProbe_RollsBackTheIncrement_FailsThePayload_AndKeepsTheLatch() + { + using CancellationTokenSource caller = new(); + TaskCompletionSource probeStarted = new(TaskCreationOptions.RunContinuationsAsynchronously); + + var port = new ProbeFakePort(async (facets, cancellationToken) => + { + if (facets.ContainsKey("applies_to")) + { + return []; + } + + probeStarted.TrySetResult(); + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + throw new UnreachableException(); + }); + + var clarificationsObject = new Clarifications(); + var provider = Provider(port, Resolved(["applies_to"])); + + using var clarifications = OpenClarifications(clarificationsObject); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var winner = InvokeSearchWithCallerTokenAsync(provider, "e33", caller.Token); + + await probeStarted.Task.WaitAsync(TestContext.Current.CancellationToken); + await caller.CancelAsync(); + + await Assert.ThrowsAnyAsync(() => winner); + + 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); + } + + [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 call 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 call 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) => + { + if (facets.ContainsKey("applies_to")) + { + return []; + } + + 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); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var winner = InvokeSearchWithCallerTokenAsync(provider, "e33", 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); + + var stopwatch = Stopwatch.StartNew(); + var loser = InvokeSearchAsync(provider, "e33 from a second caller"); + + await caller.CancelAsync(); + + await Assert.ThrowsAnyAsync(() => winner); + + var loserResult = await loser; + stopwatch.Stop(); + + 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."); + } + + [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 CallSession calls: the latch and the per-turn mark + // reset, the counter does not. + var attempts = 0; + var port = new ProbeFakePort((facets, _) => + { + if (facets.ContainsKey("applies_to")) + { + return Task.FromResult>([]); + } + + attempts++; + throw new InvalidOperationException("down"); + }); + + var clarificationsObject = new Clarifications(); + var provider = Provider(port, Resolved(["applies_to"])); + + using (OpenClarifications(clarificationsObject)) + using (KnowledgeScopeScope.Open(FullScope("applies_to", "other"))) + { + await InvokeSearchAsync(provider, "turn one"); + } + + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + + clarificationsObject.BeginTurn(); + + using (OpenClarifications(clarificationsObject)) + using (KnowledgeScopeScope.Open(FullScope("applies_to", "other"))) + { + await InvokeSearchAsync(provider, "turn two"); + } + + Assert.Equal(2, clarificationsObject.Read("applies_to").ProbeAsks); + Assert.Equal(2, attempts); + } + + [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); + + using var clarifications = OpenClarifications(clarificationsObject); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var knowledge = Resolved( + ["applies_to"], + ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 0, ProbeWaitMarginSeconds = 0 }); + var results = await InvokeSearchAsync(Provider(port, knowledge), "e33"); + + var text = Assert.Single(results).Text; + Assert.Contains("holds nothing", text, StringComparison.Ordinal); + Assert.DoesNotContain("unreachable", text, StringComparison.OrdinalIgnoreCase); + } + + [Fact] + public void ResolvedKnowledge_TheAmbiguityMembers_RoundTripThroughInit() + { + var ambiguity = new KnowledgeAmbiguityConfiguration { MaxAsks = 3 }; + var descriptions = Descriptions(("applies_to", Description)); + + var knowledge = new ResolvedKnowledge(KnowledgeMode.Tool, 5, Citations: false, Scoped: true) + { + Clarification = new ResolvedClarification + { + 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); + } + + [Fact] + public async Task Step3_HostPinnedTheWildcardValue_IsNotDropped() + { + // A host that opens a facet on 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")])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(ScopeWithOrigins( + ("brand", "acme", KnowledgeFacetOrigin.Host), + ("applies_to", "*", KnowledgeFacetOrigin.Host))); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + 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")])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(ScopeWithOrigins( + ("brand", "acme", KnowledgeFacetOrigin.Host), + ("applies_to", "*", KnowledgeFacetOrigin.Wildcard))); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + 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) + { + ["Brand"] = "acme", + ["applies_to"] = "*", + }; + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(new KnowledgeScope { Facets = facets }); + + var results = await InvokeSearchAsync(Provider(port, Resolved(["applies_to"])), "e33"); + + 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) => + { + if (facets.ContainsKey("applies_to")) + { + return []; + } + + try + { + await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false); + } + catch (OperationCanceledException) + { + await caller.CancelAsync().ConfigureAwait(false); + throw; + } + + throw new UnreachableException(); + }); + + var clarificationsObject = new Clarifications(); + using var clarifications = OpenClarifications(clarificationsObject); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + var knowledge = Resolved( + ["applies_to"], + ambiguity: new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 1 }); + + var results = await InvokeSearchWithCallerTokenAsync(Provider(port, knowledge), "e33", caller.Token); + + Assert.Single(results); + Assert.Contains("holds nothing", results[0].Text, StringComparison.Ordinal); + Assert.Equal(1, clarificationsObject.Read("applies_to").ProbeAsks); + } + + [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(); + using var clarifications = OpenClarifications(clarificationsObject); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + 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"); + + 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 + // call 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)); + } + + [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")])); + + using var clarifications = OpenClarifications(); + using var scope = KnowledgeScopeScope.Open(FullScope("applies_to", "other")); + + using CountingLoggerFactory loggers = new(RetrievedEventId); + var provider = KnowledgeProviderFactory.Create( + port, Resolved(["applies_to"]), "agent-under-test", new SourceLocatorCitationFormatter(), loggers); + + var results = await InvokeSearchAsync(provider, "e33"); + + Assert.Contains("ct900", results[0].Text, StringComparison.Ordinal); + Assert.Equal(port.Calls, loggers.Count); + Assert.Equal(2, loggers.Count); + } + + // Helpers. + + /// Log.KnowledgeProbeRan's event id: the probe's one call into host code after its search. + private const int ProbeRanEventId = 16; + + private static KnowledgeScope ScopeWithOrigins( + params (string Facet, string Value, KnowledgeFacetOrigin Origin)[] entries) + { + Dictionary facets = new(StringComparer.Ordinal); + Dictionary origins = new(StringComparer.Ordinal); + + foreach (var (facet, value, origin) in entries) + { + facets[facet] = value; + origins[facet] = origin; + } + + return new KnowledgeScope { Facets = facets, Origins = origins }; + } + + /// 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; + + internal CountingLoggerFactory(int eventId) => _logger = new CountingLogger(eventId); + + internal int Count => _logger.Count; + + public void AddProvider(ILoggerProvider provider) + { + } + + public ILogger CreateLogger(string categoryName) => _logger; + + 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 => null; + + public bool IsEnabled(LogLevel logLevel) => true; + + public void Log( + LogLevel logLevel, + EventId eventId, + TState state, + Exception? exception, + Func formatter) + { + if (eventId.Id == _eventId) + { + Interlocked.Increment(ref _count); + } + } + } + } + + /// 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; + + internal ThrowingLoggerFactory(int eventId) => _eventId = eventId; + + public void AddProvider(ILoggerProvider provider) + { + } + + public ILogger CreateLogger(string categoryName) => new ThrowingLogger(_eventId); + + public void Dispose() + { + } + + private sealed class ThrowingLogger : ILogger + { + private readonly int _eventId; + + internal ThrowingLogger(int eventId) => _eventId = eventId; + + 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) + { + if (eventId.Id == _eventId) + { + throw new InvalidOperationException("the log sink is down"); + } + } + } + } + + private static AIContextProvider Provider(IKnowledgeRetrievalPort port, ResolvedKnowledge knowledge) + => KnowledgeProviderFactory.Create( + port, knowledge, "agent-under-test", new SourceLocatorCitationFormatter(), loggers: null); + + private static IDisposable OpenClarifications(Clarifications? clarifications = null) + => TurnAmbientsTestScope.WithClarifications(clarifications ?? new Clarifications()); + + 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) + { + Clarification = new ResolvedClarification + { + 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; + } + + return map; + } + + private static KnowledgeScope FullScope(params string[] wildcardFacets) + { + Dictionary facets = new(StringComparer.Ordinal); + foreach (var facet in wildcardFacets) + { + facets[facet] = "*"; + } + + return new KnowledgeScope { Facets = facets }; + } + + private static KnowledgeCard Card(string id) + => new() { CardId = id, Text = "card " + id, ViaLink = false }; + + private static KnowledgeCard CardWithFacet(string id, string facetKey, string value, string template = "{key}") + => new() + { + 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() + { + 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; + + for (var i = parts.Length - 1; i >= 0; i--) + { + node = new Dictionary(StringComparer.Ordinal) { [parts[i]] = node }; + } + + return (IReadOnlyDictionary)node!; + } + + /// + /// Calls the factory's own search delegate directly, exactly as KnowledgeProviderFactoryTests + /// does. + /// + private static Task> InvokeSearchAsync( + AIContextProvider provider, string query) + => RunSearchDelegateAsync(provider, query, 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 call site does not read as a mistake. + /// + private static Task> InvokeSearchWithCallerTokenAsync( + AIContextProvider provider, string query, CancellationToken callerToken) + => RunSearchDelegateAsync(provider, query, callerToken); + + private static Task> RunSearchDelegateAsync( + AIContextProvider provider, string query, CancellationToken cancellationToken) + => TextSearchProviderInternals.SearchAsync(provider, query, cancellationToken); + + /// + /// A knowledge store whose answer is a function of the live 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, Task>> answer) + : this((facets, _) => answer(facets)) + { + } + + internal ProbeFakePort( + Func, CancellationToken, Task>> answer) + => _answer = answer; + + internal int Calls { get; private set; } + + public async ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + { + Calls++; + var facets = KnowledgeScopeScope.Current?.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 f6030d7c..b5e14cb6 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/KnowledgeProviderFactoryTests.cs @@ -694,36 +694,12 @@ private static AIContextProvider Provider(IKnowledgeRetrievalPort port, Resolved /// tool -- TextSearchProvider only decides which of those two happens, and in tool mode /// never calls the delegate on its own. /// - /// - /// Reaches into Microsoft.Agents.AI.TextSearchProvider's private - /// Func<string, CancellationToken, Task<IEnumerable<TextSearchResult>>> _searchAsync - /// field by reflection, verified against Microsoft.Agents.AI 1.17.0. That field is the only - /// way to reach the delegate uniformly across both SearchTime modes: in - /// OnDemandFunctionCalling the framework never calls it before the model does, and its own - /// SearchAsync(string, CancellationToken) wraps it into a formatted string rather than the - /// raw list these tests need to inspect. - /// /// The provider built. /// The search text. /// What the delegate returned. - /// - /// TextSearchProvider no longer declares the private _searchAsync field this helper - /// depends on -- a newer Microsoft.Agents.AI changed its internals and this helper needs - /// updating for the new shape, rather than the caller seeing a bare . - /// - private static async Task> InvokeSearchAsync( + private static Task> InvokeSearchAsync( AIContextProvider provider, string query) - { - var field = typeof(TextSearchProvider).GetField("_searchAsync", BindingFlags.NonPublic | BindingFlags.Instance) - ?? throw new InvalidOperationException( - "TextSearchProvider no longer has a private field named '_searchAsync'. " - + "Microsoft.Agents.AI changed its internals; update InvokeSearchAsync for the new shape."); - - var searchAsync = (Func>>) - field.GetValue(provider)!; - - return (await searchAsync(query, TestContext.Current.CancellationToken).ConfigureAwait(false)).ToList(); - } + => TextSearchProviderInternals.SearchAsync(provider, query, TestContext.Current.CancellationToken); /// Every message text of a returned context, in one string. private static string Merged(AIContext context) diff --git a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientRenderTests.cs b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientRenderTests.cs index 1d13d83e..a2852d17 100644 --- a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientRenderTests.cs +++ b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientRenderTests.cs @@ -275,7 +275,7 @@ public async Task PublishingUnderAnEarlierRenderId_KeepsItsOriginalPosition() public void TakeFor_ReturnsDistinctRenderIds_InPublishOrder() { TurnRenders renders = new(); - using var outer = OuterToolCall.Enter("call_1"); + using var outer = OuterToolCall.Enter("call_1", out _); renders.Publish("generative-ui", "b", new { title = "second" }); renders.Publish("generative-ui", "a", new { title = "first" }); diff --git a/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientStripTests.cs b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientStripTests.cs new file mode 100644 index 00000000..68f10688 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/AuditingFunctionInvokingChatClientStripTests.cs @@ -0,0 +1,158 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using AgentCore.Application.Runtime; +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: removes +/// from the ambient for the duration of a nested +/// tool call, and leaves it alone on the outermost one. +/// +/// +/// The first two facts drive directly, the same way +/// does, with the ambient hand-rolled +/// through . The third drives a real turn, +/// because that is the only place that proves CallSession.EnterAmbients actually threads its +/// own Clarifications instance through — a fact the first two cannot see, since they open the +/// ambient by hand. +/// +public sealed class AuditingFunctionInvokingChatClientStripTests +{ + [Fact] + public async Task TheCallersOwnToolCall_SeesTheHolder() + { + var clarifications = new Clarifications(); + Clarifications? seen = null; + + var tool = AIFunctionFactory.Create( + () => + { + seen = TurnAmbients.Current?.Clarifications; + return "done."; + }, + "search_tool", + "Reads the ambient."); + + using var scope = TurnAmbients.Amend(ambients => ambients with { Clarifications = clarifications }); + + ToolCallingChatClient inner = new("the loop continues."); + using AuditingFunctionInvokingChatClient client = new(inner); + ChatOptions options = new() { Tools = [tool] }; + + 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 ambient 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( + () => + { + seenNested = TurnAmbients.Current?.Clarifications; + return "inner done."; + }, + "inner_tool", + "Reads the ambient from inside a nested loop."); + + var outerTool = AIFunctionFactory.Create( + async () => + { + seenOutside = TurnAmbients.Current?.Clarifications; + + ToolCallingChatClient innerModel = new("nested done."); + using AuditingFunctionInvokingChatClient innerClient = new(innerModel); + ChatOptions innerOptions = new() { Tools = [innerTool] }; + await innerClient.GetResponseAsync( + [new ChatMessage(ChatRole.User, "go")], innerOptions, TestContext.Current.CancellationToken); + + return "outer done."; + }, + "outer_tool", + "Runs a nested loop."); + + using var scope = TurnAmbients.Amend(ambients => ambients with { Clarifications = clarifications }); + + ToolCallingChatClient outerModel = new("done."); + using AuditingFunctionInvokingChatClient outerClient = new(outerModel); + ChatOptions outerOptions = new() { Tools = [outerTool] }; + + await outerClient.GetResponseAsync( + [new ChatMessage(ChatRole.User, "go")], outerOptions, TestContext.Current.CancellationToken); + + Assert.Same(clarifications, seenOutside); + Assert.Null(seenNested); + } + + // ------------------------------------------------------------------------------------------- + // The wiring fact: a real CallSession turn opens its own Clarifications and threads it through + // EnterAmbients, so the model's own (outermost) knowledge search sees it, exactly as the two + // hand-rolled facts above predict once CallSession is actually driving. + // ------------------------------------------------------------------------------------------- + [Fact] + public async Task RunTurnAsync_AToolModeKnowledgeSearch_SeesTheHolder() + { + const string yaml = """ + apiVersion: agentcore/v1 + name: clarifications-through-callsession + agents: + items: + - id: only + instructions: "answer the caller" + knowledge: { mode: tool, scoped: false } + policy: + initial: greeting + stages: + - { id: greeting, agent: only } + """; + + var port = new StubKnowledgePort([Card("a")]); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(new FakeChatClientFactory( + new ToolCallingChatClient( + "done.", + new Dictionary(StringComparer.Ordinal) { ["userQuestion"] = "what is it" }))) + { + Knowledge = port, + }); + + var factory = new CallSessionFactory(compiled, new GuardEvaluator(compiled.Configuration.Guards)); + var session = factory.Create("call-strip-1"); + + await session.RunTurnAsync("what is it", TestContext.Current.CancellationToken); + + Assert.Equal(1, port.Calls); + Assert.NotNull(port.ClarificationsAtTheStore); + } + + 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/CallSessionClarificationTests.cs b/tests/AgentCore.Application.Tests/Runtime/CallSessionClarificationTests.cs new file mode 100644 index 00000000..40060bd8 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/CallSessionClarificationTests.cs @@ -0,0 +1,363 @@ +using System.Runtime.CompilerServices; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using AgentCore.Application.Runtime; +using AgentCore.Application.State; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Knowledge.Fakes; +using AgentCore.Domain.Knowledge; +using AgentCore.TestSupport; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Runtime; + +/// +/// Channel 1 (§7), driven through two real turns rather than by seeding the +/// ambient — K35's ordering is the thing under test: a near-tie the linker finds on turn 1 must reach +/// the model only on turn 2's own invocation, and never on a delegated sub-agent's. +/// +public sealed class CallSessionClarificationTests +{ + private const string AppliesToDescription = "The model, as printed on the machine."; + + private const string Yaml = + """ + apiVersion: agentcore/v1 + name: clarification-two-turn + state: + applies_to: + type: string + writer: extractor + description: "The model, as printed on the machine." + vocabulary: { from: knowledge } + extractor: + model: { ref: fill } + when: after_reply + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [applies_to] + wildcard: { value: "*", facets: [applies_to] } + ambiguity: { maxCandidates: 6, maxAsks: 2 } + agents: + items: + - id: only + """; + + private const string PrefetchYaml = + """ + apiVersion: agentcore/v1 + name: clarification-two-turn-prefetch + state: + applies_to: + type: string + writer: extractor + description: "The model, as printed on the machine." + vocabulary: { from: knowledge } + extractor: + model: { ref: fill } + when: after_reply + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [applies_to] + wildcard: { value: "*", facets: [applies_to] } + ambiguity: { maxCandidates: 6, maxAsks: 2 } + agents: + items: + - id: only + knowledge: { mode: prefetch, scoped: false } + """; + + private const string DelegationYaml = + """ + apiVersion: agentcore/v1 + name: clarification-delegation + state: + applies_to: + type: string + writer: extractor + description: "The model, as printed on the machine." + vocabulary: { from: knowledge } + extractor: + model: { ref: fill } + when: after_reply + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [applies_to] + wildcard: { value: "*", facets: [applies_to] } + ambiguity: { maxCandidates: 6, maxAsks: 2 } + tools: + - { id: ask_specialist, kind: agent, agent: specialist, description: Ask the specialist. } + agents: + defaults: + model: { ref: reply } + items: + - id: only + tools: [ ask_specialist ] + - id: specialist + model: { ref: specialist } + policy: + initial: greeting + stages: + - { id: greeting, agent: only } + """; + + [Fact] + public async Task NearTieOnTurn1_TurnTwosInvocationCarriesTheInstruction() + { + using SequencedChatClient reply = new( + "I don't have that on file yet.", + """{"applies_to":"the CT900"}""", + "let me check on that for you.", + "{}"); + + var session = Build(reply); + + await session.RunTurnAsync("I have a CT900 and a CT900ENT", TestContext.Current.CancellationToken); + + // Turn 1: nothing was pending before the extractor ran, so the caller's own turn carries no + // clarification. It is the near-tie itself, found by the linker after the model already + // answered — the linker's Ambiguous outcome does not retract what was just said (K16, K29). + Assert.Equal(string.Empty, reply.SystemText(0)); + + await session.RunTurnAsync("okay, thanks", TestContext.Current.CancellationToken); + + Assert.Equal( + ClarificationText.Instruction(AppliesToDescription, ["CT900", "CT900ENT"], 6, first: true), + reply.SystemText(2)); + } + + [Fact] + public async Task SameNearTie_InPrefetchMode_OnATurnWithNoToolCall_TheClarificationStillArrives() + { + // K29: the guard reads TurnContextScope, not the knowledge provider's own mode. Bound with a + // real StubKnowledgePort so this also proves the instruction rides alongside a second real + // provider's own card, rather than replacing it (K16). + using SequencedChatClient reply = new( + "I don't have that on file yet.", + """{"applies_to":"the CT900"}""", + "let me check on that for you.", + "{}"); + + var port = new StubKnowledgePort([Card("a")]); + var session = Build(reply, PrefetchYaml, port); + + await session.RunTurnAsync("I have a CT900 and a CT900ENT", TestContext.Current.CancellationToken); + await session.RunTurnAsync("okay, thanks", TestContext.Current.CancellationToken); + + // Prefetch mode means the model never calls a search tool at all, so this is also the "turn + // where the model calls no tool" half of the clause. The prefetch search itself ran (Calls + // is 2, once per turn) with no tool round involved anywhere. + Assert.Equal(2, port.Calls); + + var turn2 = reply.Requests[2]; + Assert.Contains(turn2, message => message.Text.Contains("card a", StringComparison.Ordinal)); + Assert.Contains( + turn2, + message => message.Text.Equals( + ClarificationText.Instruction(AppliesToDescription, ["CT900", "CT900ENT"], 6, first: true), + StringComparison.Ordinal)); + } + + [Fact] + public async Task DelegatedRun_CarriesNoInstruction_AndCountsNothing() + { + // K29: every kind: agent delegation is a fresh RunAsync on a fresh session, so the same + // session guard that protects a graph row protects a sub-agent too. + ScriptedDelegatingChatClient mainAgent = new( + (ToolName: null, Text: "okay, one moment."), + (ToolName: "ask_specialist", Text: string.Empty), + (ToolName: null, Text: "here is what the specialist said.")); + SequencedChatClient specialist = new("the specialist's answer."); + SequencedChatClient extractor = new("""{"applies_to":"the CT900"}""", "{}"); + + RoutingChatClientFactory chatClients = new(mainAgent); + chatClients.Route("reply", mainAgent); + chatClients.Route("specialist", specialist); + chatClients.Route("fill", extractor); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(DelegationYaml), new AgentCompilationContext(chatClients)); + var stateExtractor = CallSessionFactory.CreateExtractor(compiled, chatClients); + VocabularyCache vocabulary = new(); + vocabulary.Replace("applies_to", ["CT900", "CT900ENT"], maxValues: 2000); + + var session = new CallSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), stateExtractor, vocabulary: vocabulary) + .Create("call-delegation"); + + await session.RunTurnAsync("I have a CT900 and a CT900ENT", TestContext.Current.CancellationToken); + await session.RunTurnAsync("ask the specialist", TestContext.Current.CancellationToken); + + const string named = "is not yet known"; + + // "one injected message" is a fact about ONE ClarificationProvider.InvokingAsync call, proven + // directly (with real access to the counter) by ClarificationProviderTests. The framework + // resends the base message list on every round of one RunAsync's tool loop, so the same + // injected line legitimately reaches the model more than once here — turn 2 calls the tool + // and then answers, two rounds of the same invocation. What only a real delegated run can + // prove is the other half: the specialist's own nested RunAsync must see none of it, on any + // of its own rounds, even though the same ClarificationProvider is bound to it too. + Assert.Equal(string.Empty, mainAgent.SystemText(0)); + Assert.Contains(named, mainAgent.SystemText(1), StringComparison.Ordinal); + Assert.Contains(named, mainAgent.SystemText(2), StringComparison.Ordinal); + + Assert.NotEmpty(specialist.Requests); + for (var request = 0; request < specialist.Requests.Count; request++) + { + Assert.DoesNotContain(named, specialist.SystemText(request), StringComparison.Ordinal); + } + } + + private static CallSession Build(SequencedChatClient reply, string yaml = Yaml, StubKnowledgePort? port = null) + { + var chatClients = new FakeChatClientFactory(reply); + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(chatClients) { Knowledge = port }); + + var extractor = CallSessionFactory.CreateExtractor(compiled, chatClients); + VocabularyCache vocabulary = new(); + vocabulary.Replace("applies_to", ["CT900", "CT900ENT"], maxValues: 2000); + + return new CallSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), extractor, vocabulary: vocabulary) + .Create("call-1"); + } + + 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, + }; + + /// + /// A model that calls a scripted tool name (or none) on each request, and records the full + /// message list of every request it answered — plus + /// 's tool-emitting behaviour, combined, because the delegation + /// row needs both: a deterministic per-call script (turn 1 must not call the tool) and full + /// message visibility (to read the system text a real provider chain produced). + /// + private sealed class ScriptedDelegatingChatClient : IChatClient + { + private readonly (string? ToolName, string Text)[] _script; + private int _calls; + + public ScriptedDelegatingChatClient(params (string? ToolName, string Text)[] script) => _script = script; + + public List> Requests { get; } = []; + + public string SystemText(int request) + { + lock (Requests) + { + return string.Join( + '\n', + Requests[request].Where(message => message.Role == ChatRole.System).Select(message => message.Text)); + } + } + + 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) + { + Requests.Add([.. messages]); + } + + await Task.Yield(); + + var (toolName, text) = _script[Math.Min(index, _script.Length - 1)]; + var responseId = Guid.NewGuid().ToString("N"); + + if (toolName is not null) + { + // AgentDelegationTool.Create wraps the inner agent through AsAIFunction(), which + // generates a required string argument named "query". A call with no arguments fails + // schema validation before the specialist is ever reached. + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + $"call_{index}", + toolName, + new Dictionary(StringComparer.Ordinal) { ["query"] = "check the model" })]) + { + ResponseId = responseId, + MessageId = responseId, + }; + yield break; + } + + yield return new ChatResponseUpdate(ChatRole.Assistant, text) + { + 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. + } + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/CallSessionProbeTests.cs b/tests/AgentCore.Application.Tests/Runtime/CallSessionProbeTests.cs new file mode 100644 index 00000000..10e57e3f --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/CallSessionProbeTests.cs @@ -0,0 +1,282 @@ +using System.Runtime.CompilerServices; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using AgentCore.Application.Knowledge; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.State; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Domain.Knowledge; +using AgentCore.TestSupport; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Runtime; + +/// +/// §8's probe, and §7's channel 1, driven through real turns rather than by +/// seeding the ambient: the genuinely two-turn rows (K43's latch reset against K22's persistent +/// counter) and the genuinely graph-shaped row (K39) — both need the real turn loop's own +/// BeginTurn and row-kind wiring, which KnowledgeProbeTests's ambient-level tests +/// cannot exercise. +/// +public sealed class CallSessionProbeTests +{ + private const string AppliesToDescription = "The model, as printed on the machine."; + + private const string BrandDescription = "The brand of the caller's machine."; + + /// Two agents, run in order. Neither is scoped for search; both share channel 1. + private const string GraphYaml = + """ + apiVersion: agentcore/v1 + name: probe-graph + state: + applies_to: + type: string + writer: extractor + description: "The model, as printed on the machine." + vocabulary: { from: knowledge } + extractor: + model: { ref: fill } + when: after_reply + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [applies_to] + wildcard: { value: "*", facets: [applies_to] } + ambiguity: { maxCandidates: 6, maxAsks: 2 } + agents: + items: + - { id: researcher, model: { ref: researcher }, instructions: "look things up" } + - { id: responder, model: { ref: responder }, instructions: "answer the caller" } + graph: + pattern: sequential + agents: [ researcher, responder ] + """; + + /// One tool-mode, scoped agent over two droppable facets, so K33 never blocks the drop. + private const string ProbeYaml = + """ + apiVersion: agentcore/v1 + name: probe-two-turn + state: + applies_to: + type: string + writer: extractor + description: "The model, as printed on the machine." + vocabulary: { from: knowledge } + brand: + type: string + writer: extractor + description: "The brand of the caller's machine." + vocabulary: { from: knowledge } + extractor: + model: { ref: fill } + when: after_reply + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "{key}" + fromState: [applies_to, brand] + wildcard: { value: "*", facets: [applies_to, brand] } + ambiguity: { maxCandidates: 6, maxAsks: 2 } + agents: + defaults: + model: { ref: reply } + items: + - id: only + knowledge: { mode: tool, scoped: true } + """; + + [Fact] + public async Task K39_GraphDocument_Channel1SaysNothing_OnEitherTurn() + { + // K39: channel 1's session guard passes only on a row whose session carries history -- rows 1 + // and 2. A graph row's participants each run on a session that is never the call's own, so the + // clarification a near-tie arms on turn 1 must stay silent for both nodes on turn 2 as well, + // where CallSessionClarificationTests proves it speaks on a row 1/2 document. + const string named = "is not yet known"; + + using ScriptedChatClient researcher = new("Let me check the order system."); + using ScriptedChatClient responder = new("Order 41 ships Friday."); + SequencedChatClient extractor = new("""{"applies_to":"the CT900"}""", "{}"); + + RoutingChatClientFactory chatClients = new(researcher); + chatClients.Route("researcher", researcher); + chatClients.Route("responder", responder); + chatClients.Route("fill", extractor); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(GraphYaml), new AgentCompilationContext(chatClients)); + var stateExtractor = CallSessionFactory.CreateExtractor(compiled, chatClients); + VocabularyCache vocabulary = new(); + vocabulary.Replace("applies_to", ["CT900", "CT900ENT"], maxValues: 2000); + + var session = new CallSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), stateExtractor, vocabulary: vocabulary) + .Create("call-graph-probe"); + + await session.RunTurnAsync("I have a CT900 and a CT900ENT", TestContext.Current.CancellationToken); + await session.RunTurnAsync("okay, thanks", TestContext.Current.CancellationToken); + + Assert.DoesNotContain(named, researcher.FullText, StringComparison.Ordinal); + Assert.DoesNotContain(named, responder.FullText, StringComparison.Ordinal); + } + + [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 CallSession). + 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.Compile( + ConfigurationLoader.LoadYaml(ProbeYaml), + new AgentCompilationContext(chatClients) { Knowledge = port }); + var stateExtractor = CallSessionFactory.CreateExtractor(compiled, chatClients); + VocabularyCache vocabulary = new(); + vocabulary.Replace("applies_to", ["CT900", "CT900ENT"], maxValues: 2000); + vocabulary.Replace("brand", ["sole", "spirit"], maxValues: 2000); + + var session = new CallSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), stateExtractor, vocabulary: vocabulary) + .Create("call-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; + + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + { + if (KnowledgeScopeScope.Current?.Facets.Count == 2) + { + return ValueTask.FromResult>([]); + } + + _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 ScriptedToolCallingChatClient(params (string? ToolName, string? Text)[] script) => _script = script; + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + + var index = Interlocked.Increment(ref _calls) - 1; + await Task.Yield(); + + var (toolName, text) = _script[Math.Min(index, _script.Length - 1)]; + var responseId = Guid.NewGuid().ToString("N"); + + if (toolName is not null) + { + yield return new ChatResponseUpdate( + ChatRole.Assistant, + [new FunctionCallContent( + $"call_{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, + }; + } + + 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. + } + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/ClarificationProviderTests.cs b/tests/AgentCore.Application.Tests/Runtime/ClarificationProviderTests.cs new file mode 100644 index 00000000..4c233603 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/ClarificationProviderTests.cs @@ -0,0 +1,540 @@ +using System.Text.Json; +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Knowledge; +using AgentCore.Application.Runtime; +using AgentCore.Application.State; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Knowledge.Fakes; +using AgentCore.Domain.Knowledge; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Runtime; + +/// +/// : §7 channel 1's loop, driven directly against a hand-built +/// and rather than a real turn. The rows that +/// depend on 's own turn ordering (K35) live in +/// instead. +/// +public sealed class ClarificationProviderTests +{ + private const string AppliesToDescription = "The model, as printed on the machine."; + + private const string BrandDescription = "The brand of the caller's machine."; + + private const string AmbiguityYaml = + """ + apiVersion: agentcore/v1 + name: clarification-wiring + state: + applies_to: { type: string, writer: extractor, description: "The model, as printed on the machine.", vocabulary: { from: knowledge } } + extractor: + model: { ref: fill } + when: after_reply + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [applies_to] + wildcard: { value: "*", facets: [applies_to] } + ambiguity: { maxCandidates: 6, maxAsks: 2 } + agents: + items: + - id: only + knowledge: { mode: prefetch, scoped: false } + """; + + private const string NoAmbiguityYaml = + """ + apiVersion: agentcore/v1 + name: clarification-wiring-none + agents: + items: + - id: only + """; + + [Fact] + public void CompiledAgent_CarriesTheProvider_BeforeTheKnowledgeProvider_WhenAmbiguityIsDeclared() + { + using SequencedChatClient reply = new("hello there."); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(AmbiguityYaml), + new AgentCompilationContext(new FakeChatClientFactory(reply)) + { + Knowledge = new StubKnowledgePort([]), + }); + + var agent = ChatClientAgentOf(Assert.Single(compiled.Agents.Values)); + var providers = agent.AIContextProviders ?? []; + + var clarificationIndex = providers.ToList().FindIndex(p => p is ClarificationProvider); + var knowledgeIndex = providers.ToList().FindIndex( + p => p.GetType().Name.Contains("TextSearchProvider", StringComparison.Ordinal)); + + Assert.True(clarificationIndex >= 0, "the compiled agent must carry a ClarificationProvider."); + Assert.True(knowledgeIndex >= 0, "the compiled agent must still carry the knowledge provider."); + Assert.True(clarificationIndex < knowledgeIndex, "the clarification must bind before the knowledge provider."); + } + + [Fact] + public void CompiledAgent_CarriesNoProvider_WhenTheDocumentDeclaresNoAmbiguity() + { + // K19: an undeclared ambiguity: must not change what a document without it compiles to. + using SequencedChatClient reply = new("hello there."); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(NoAmbiguityYaml), new AgentCompilationContext(new FakeChatClientFactory(reply))); + + var agent = ChatClientAgentOf(Assert.Single(compiled.Agents.Values)); + var providers = agent.AIContextProviders ?? []; + + Assert.DoesNotContain(providers, p => p is ClarificationProvider); + } + + /// Reads the under whatever the compiler wrapped it in. + private static ChatClientAgent ChatClientAgentOf(AIAgent agent) + { + var inner = agent.GetService(); + Assert.NotNull(inner); + return inner; + } + + [Fact] + public async Task NoTurnIsOpen_EmitsNothing() + { + var provider = Provider(maxAsks: 2, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + var context = await provider.InvokingAsync(Invoking(new StubSession()), TestContext.Current.CancellationToken); + + Assert.Null(context.Messages); + } + + [Fact] + public async Task ARunOnAnotherSession_EmitsNothing() + { + // The K29 guard: a delegated kind: agent run's session never matches the caller's own turn. + StubSession callSession = new(); + StubSession delegatedSession = new(); + var clarifications = new Clarifications(); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + + var provider = Provider(maxAsks: 2, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var turn = TurnContextScope.Enter(new TurnContext { Session = callSession }); + using var ambients = TurnAmbients.Amend( + a => a with { State = State(("applies_to", AppliesToDescription)), Clarifications = clarifications }); + + var context = await provider.InvokingAsync( + Invoking(delegatedSession), TestContext.Current.CancellationToken); + + Assert.Null(context.Messages); + Assert.Equal(0, clarifications.Read("applies_to").NamedAsks); + } + + [Fact] + public async Task MaxAsksZero_InjectsNothing_EvenWithAPendingSlot() + { + // K38's gate-only mode: the vocabulary and the gate still work, but the channel never speaks. + StubSession session = new(); + var clarifications = new Clarifications(); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + + var provider = Provider(maxAsks: 0, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, State(("applies_to", AppliesToDescription)), clarifications); + + var context = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + + Assert.Null(context.Messages); + Assert.Equal(0, clarifications.Read("applies_to").NamedAsks); + } + + [Fact] + public async Task NegativeMaxAsks_InjectsNothing_RatherThanLettingTheResetAskOnce() + { + // K38 again, at a maxAsks the schema does not itself bound. An == 0 gate would fall through + // to step 2's failing namedAsks < maxAsks test and let step 3's one reset speak. + StubSession session = new(); + var clarifications = new Clarifications(); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + + var provider = Provider(maxAsks: -1, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, State(("applies_to", AppliesToDescription)), clarifications); + + var context = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + + Assert.Null(context.Messages); + Assert.Equal(0, clarifications.Read("applies_to").NamedAsks); + Assert.False(clarifications.Read("applies_to").ResetSpent); + } + + [Fact] + public async Task ATurnThatNeverCommits_IsNotCharged_AndAsksAgainNextTurn() + { + // The instruction is injected before the run. A run that ended in the fallback reply never + // put the question, so the next turn must ask it rather than treat the slot as answered. + StubSession session = new(); + var clarifications = new Clarifications(); + var state = State(("applies_to", AppliesToDescription)); + + var provider = Provider(maxAsks: 1, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, state, clarifications); + + clarifications.BeginTurn(); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + var turn1 = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + Assert.NotNull(turn1.Messages); + + // Turn 1 threw or fell back: nothing commits it. + clarifications.BeginTurn(); + var turn2 = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + + Assert.NotNull(turn2.Messages); + Assert.Equal(1, clarifications.Read("applies_to").NamedAsks); + } + + [Fact] + public async Task NoPendingList_EmitsNothing() + { + StubSession session = new(); + var clarifications = new Clarifications(); + + var provider = Provider(maxAsks: 2, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, State(("applies_to", AppliesToDescription)), clarifications); + + var context = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + + Assert.Null(context.Messages); + } + + [Fact] + public async Task AFilledSlot_IsSkipped_EvenWithAStalePendingList() + { + // Belt and braces: K30 clears Pending on a successful write, but the loop's own "still + // unfilled" test must not tell the model a filled slot "is not yet known" regardless. + StubSession session = new(); + var clarifications = new Clarifications(); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + + var state = State(("applies_to", AppliesToDescription)); + state.TryWrite("applies_to", JsonSerializer.SerializeToNode("ct900ent")); + + var provider = Provider(maxAsks: 2, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, state, clarifications); + + var context = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + + Assert.Null(context.Messages); + } + + [Fact] + public async Task APendingSlot_SpeaksOnce_AndRecordsWhatWasNamed() + { + StubSession session = new(); + var clarifications = new Clarifications(); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + + var provider = Provider(maxAsks: 2, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, State(("applies_to", AppliesToDescription)), clarifications); + + var context = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + + var message = Assert.Single(context.Messages!); + Assert.Equal(ChatRole.System, message.Role); + Assert.Equal( + ClarificationText.Instruction(AppliesToDescription, ["ct900", "ct900ent"], 6, first: true), + message.Text); + + var snapshot = clarifications.Read("applies_to"); + Assert.Equal(1, snapshot.NamedAsks); + Assert.True(snapshot.AskedThisTurn); + Assert.Equal(Clarifications.LastNamedKind.Set, snapshot.LastNamed.Kind); + Assert.Equal(new HashSet(StringComparer.Ordinal) { "ct900", "ct900ent" }, snapshot.LastNamed.Values); + } + + [Fact] + public async Task TheUnchangedSet_IsNotAskedAgain_UntilItChanges() + { + // K37: the caller has already been asked this exact question. maxAsks: 1 makes the reset + // reachable in a small number of simulated turns. + StubSession session = new(); + var clarifications = new Clarifications(); + var state = State(("applies_to", AppliesToDescription)); + + var provider = Provider(maxAsks: 1, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, state, clarifications); + + // Turn 1: pending set A is new. Asked once (namedAsks -> 1). Each turn here commits, which + // is what CallSession does once the turn's own words reach the caller. + clarifications.BeginTurn(); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + var turn1 = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + Assert.NotNull(turn1.Messages); + Assert.Equal(1, clarifications.Read("applies_to").NamedAsks); + clarifications.CommitAsks(); + + // Turn 2: the same set. namedAsks is at the cap (1), but K37 suppresses before the cap is + // even reached, because nothing changed. + clarifications.BeginTurn(); + var turn2 = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + Assert.Null(turn2.Messages); + Assert.Equal(1, clarifications.Read("applies_to").NamedAsks); + Assert.False(clarifications.Read("applies_to").ResetSpent); + clarifications.CommitAsks(); + + // Turn 3: the set changes. namedAsks is at the cap and differs from lastNamed, so the one + // reset fires: namedAsks returns to 1 (not 0), and the reset is spent. + clarifications.BeginTurn(); + clarifications.Update("applies_to", s => s.Pending = ["ct800", "ct800ent"]); + var turn3 = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + Assert.NotNull(turn3.Messages); + clarifications.CommitAsks(); + var afterReset = clarifications.Read("applies_to"); + Assert.Equal(1, afterReset.NamedAsks); + Assert.True(afterReset.ResetSpent); + Assert.Equal( + new HashSet(StringComparer.Ordinal) { "ct800", "ct800ent" }, afterReset.LastNamed.Values); + + // Turn 4: the set changes again. The reset is already spent, so nothing is asked — the + // call's total stays at exactly 2 x maxAsks = 2, matching turn 1 and turn 3. + clarifications.BeginTurn(); + clarifications.Update("applies_to", s => s.Pending = ["xt285", "xt385"]); + var turn4 = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + Assert.Null(turn4.Messages); + Assert.Equal(1, clarifications.Read("applies_to").NamedAsks); + } + + [Fact] + public async Task TwoDifferentOverCapSets_AreNotBothSpoken() + { + // K37: above maxCandidates neither channel names a list, so two different over-cap sets read + // as the identical question and the sentinel record suppresses the second. + StubSession session = new(); + var clarifications = new Clarifications(); + var state = State(("applies_to", AppliesToDescription)); + + var provider = Provider(maxAsks: 2, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, state, clarifications); + + clarifications.BeginTurn(); + clarifications.Update("applies_to", s => s.Pending = ["a", "b", "c", "d", "e", "f", "g"]); + var turn1 = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + Assert.NotNull(turn1.Messages); + Assert.Equal(1, clarifications.Read("applies_to").NamedAsks); + clarifications.CommitAsks(); + + clarifications.BeginTurn(); + clarifications.Update("applies_to", s => s.Pending = ["h", "i", "j", "k", "l", "m", "n"]); + var turn2 = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + + Assert.Null(turn2.Messages); + Assert.Equal(1, clarifications.Read("applies_to").NamedAsks); + } + + [Fact] + public async Task TwoPendingSlots_SpeakTwoMessages_AndTheSecondOpensWithAnotherThing() + { + StubSession session = new(); + var clarifications = new Clarifications(); + clarifications.Update("brand", s => s.Pending = ["sole", "spirit"]); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + + var provider = Provider( + maxAsks: 2, + maxCandidates: 6, + ("brand", BrandDescription), + ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn( + session, State(("brand", BrandDescription), ("applies_to", AppliesToDescription)), clarifications); + + var context = await provider.InvokingAsync(Invoking(session), TestContext.Current.CancellationToken); + + Assert.NotNull(context.Messages); + var messages = context.Messages!.ToList(); + Assert.Equal(2, messages.Count); + Assert.StartsWith("One thing is not yet known: ", messages[0].Text, StringComparison.Ordinal); + Assert.StartsWith("Another thing is not yet known: ", messages[1].Text, StringComparison.Ordinal); + } + + [Fact] + public async Task TheInstructionNeverRemovesACard() + { + // Chained the way MAF actually runs two providers on one agent: each InvokingAsync merges + // onto the context the one before it returned, so this proves the clarification is added + // context rather than a replacement — with no CallSession in between to obscure which + // provider did what. + StubSession session = new(); + var clarifications = new Clarifications(); + clarifications.Update("applies_to", s => s.Pending = ["ct900", "ct900ent"]); + + var knowledgeProvider = KnowledgeProviderFactory.Create( + new StubKnowledgePort([Card("a")]), + new ResolvedKnowledge(KnowledgeMode.Prefetch, Limit: 5, Citations: false, Scoped: false), + "agent-under-test", + new SourceLocatorCitationFormatter(), + loggers: null); + var clarificationProvider = Provider(maxAsks: 2, maxCandidates: 6, ("applies_to", AppliesToDescription)); + + using var scope = OpenTurn(session, State(("applies_to", AppliesToDescription)), clarifications); + + var afterKnowledge = await knowledgeProvider.InvokingAsync( + Invoking(session, "the screen says e33"), TestContext.Current.CancellationToken); + Assert.Contains(afterKnowledge.Messages!, message => message.Text.Contains("card a", StringComparison.Ordinal)); + +#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. + var merged = await clarificationProvider.InvokingAsync( + new AIContextProvider.InvokingContext(StubAgent.Instance, session, afterKnowledge), + TestContext.Current.CancellationToken); +#pragma warning restore MAAI001 + + Assert.Contains(merged.Messages!, message => message.Text.Contains("card a", StringComparison.Ordinal)); + Assert.Contains( + merged.Messages!, + message => message.Text.Contains("is not yet known", StringComparison.Ordinal)); + } + + private static ClarificationProvider Provider( + int maxAsks, int maxCandidates, params (string Slot, string Description)[] slots) + => new( + new KnowledgeAmbiguityConfiguration { MaxAsks = maxAsks, MaxCandidates = maxCandidates }, + [.. slots.Select(slot => slot.Slot)], + slots.ToDictionary(slot => slot.Slot, string? (slot) => slot.Description, StringComparer.Ordinal)); + + private static StateDocument State(params (string Slot, string Description)[] slots) + { + Dictionary declared = new(StringComparer.Ordinal); + foreach (var (slot, description) in slots) + { + declared[slot] = new StateSlotConfiguration + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + Description = description, + }; + } + + var configuration = new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Name = "clarification-provider-tests", + State = declared, + }; + + return new StateDocument(configuration); + } + + private static Scope OpenTurn(AgentSession session, StateDocument state, Clarifications clarifications) + { + var outer = TurnContextScope.Enter(new TurnContext { Session = session }); + var inner = TurnAmbients.Amend(a => a with { State = state, Clarifications = clarifications }); + return new Scope(outer, inner); + } + + /// + /// Runs the provider the way the framework runs it, over an otherwise empty context — so + /// context.Messages on the result is exactly what this provider itself contributed, with + /// no caller message riding along to make a null-versus-empty assertion pass by accident. + /// + private static AIContextProvider.InvokingContext Invoking(AgentSession session) + { +#pragma warning disable MAAI001 // The context constructors are the framework's own experimental surface. + return new(StubAgent.Instance, session, new AIContext()); +#pragma warning restore MAAI001 + } + + /// Runs the provider with a caller message in view, for the knowledge provider's query. + private static AIContextProvider.InvokingContext Invoking(AgentSession session, string text) + { +#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 KnowledgeCard Card(string id) + => new() + { + CardId = id, + Text = "card " + id, + Authority = 3, + SourceRef = "ct900-om", + SourceLocator = "p.27", + Score = 0.87, + ViaLink = false, + }; + + private sealed class Scope : IDisposable + { + private readonly IDisposable _outer; + private readonly IDisposable _inner; + + public Scope(IDisposable outer, IDisposable inner) + { + _outer = outer; + _inner = inner; + } + + public void Dispose() + { + _inner.Dispose(); + _outer.Dispose(); + } + } + + 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(); + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/ClarificationTextTests.cs b/tests/AgentCore.Application.Tests/Runtime/ClarificationTextTests.cs new file mode 100644 index 00000000..f01154dc --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/ClarificationTextTests.cs @@ -0,0 +1,155 @@ +using AgentCore.Application.Runtime; +using Xunit; + +namespace AgentCore.Application.Tests.Runtime; + +/// +/// The sentences §7 specifies for both ambiguity channels, rendered against §4's own +/// description: values so a human can read the result as English rather than a template. +/// +public sealed class ClarificationTextTests +{ + // §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 Instruction_TwoCandidates_FirstMessage_RendersTheBaseSentence() + { + var text = ClarificationText.Instruction( + AppliesToDescription, ["ct900", "ct900ent"], maxCandidates: 6, first: true); + + Assert.Equal( + "One thing is not yet known: The model, as printed on the machine. It is one of ct900 or " + + "ct900ent. Ask the caller, and do not give advice that is specific to one until they answer. " + + "Anything that applies to all of them is still fair game.", + text); + } + + [Fact] + public void Instruction_ThreeCandidates_JoinsWithAnOxfordComma() + { + var text = ClarificationText.Instruction( + AppliesToDescription, ["ct800", "ct900", "ct900ent"], maxCandidates: 6, first: true); + + Assert.Equal( + "One thing is not yet known: The model, as printed on the machine. It is one of ct800, ct900, " + + "or ct900ent. Ask the caller, and do not give advice that is specific to one until they answer. " + + "Anything that applies to all of them is still fair game.", + text); + } + + [Fact] + public void Instruction_OneCandidate_RendersTheConfirmSentence() + { + var text = ClarificationText.Instruction( + AppliesToDescription, ["ct900"], maxCandidates: 6, first: true); + + Assert.Equal( + "One thing 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 giving advice specific to it.", + text); + } + + [Fact] + public void Instruction_OverMaxCandidates_OmitsTheList() + { + var text = ClarificationText.Instruction( + AppliesToDescription, + ["ct800", "ct800ent", "ct900", "ct900ent", "xt285", "xt385", "xt485"], + maxCandidates: 6, + first: true); + + Assert.Equal( + "One thing is not yet known: The model, as printed on the machine. Ask the caller, and do not " + + "give advice specific to one until they answer.", + text); + } + + [Fact] + public void Instruction_SecondMessage_OpensWithAnotherThing() + { + var text = ClarificationText.Instruction( + BrandDescription, ["sole", "spirit"], maxCandidates: 6, first: false); + + Assert.StartsWith("Another thing is not yet known: ", text, StringComparison.Ordinal); + Assert.DoesNotContain("One thing is not yet known", text, StringComparison.Ordinal); + } + + [Fact] + public void Instruction_SecondMessage_OneCandidate_OpensWithAnotherThing() + { + var text = ClarificationText.Instruction( + AppliesToDescription, ["ct900"], maxCandidates: 6, first: false); + + Assert.StartsWith("Another thing is not yet confirmed: ", text, StringComparison.Ordinal); + } + + [Fact] + public void Instruction_DescriptionFallsBackToTheSlotName_WhenTheCallerPassesIt() + { + // ClarificationText itself does not know about slots; the fallback to the slot name is the + // caller's job (ClarificationProvider). This fact only pins that the renderer treats + // whatever string it is given as the apposition, verbatim. + var text = ClarificationText.Instruction("applies_to", ["ct900", "ct900ent"], maxCandidates: 6, first: true); + + Assert.Equal( + "One thing is not yet known: applies_to It is one of ct900 or ct900ent. Ask the caller, and do " + + "not give advice that is specific to one until they answer. Anything that applies to all of " + + "them is still fair game.", + text); + } + + [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() + { + 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); + } + + [Fact] + public void TwoOverCapSets_RenderTheIdenticalSentence() + { + // K37: two different over-maxCandidates sets say the same thing, which is what lets the + // sentinel record suppress the second one as a repeat rather than a new question. + var first = ClarificationText.Instruction( + AppliesToDescription, ["a", "b", "c", "d", "e", "f", "g"], maxCandidates: 6, first: true); + var second = ClarificationText.Instruction( + AppliesToDescription, ["h", "i", "j", "k", "l", "m", "n"], maxCandidates: 6, first: true); + + Assert.Equal(first, second); + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/ClarificationsTests.cs b/tests/AgentCore.Application.Tests/Runtime/ClarificationsTests.cs new file mode 100644 index 00000000..223ca23b --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/ClarificationsTests.cs @@ -0,0 +1,394 @@ +using AgentCore.Application.Runtime; +using Microsoft.Agents.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Runtime; + +/// +/// : the per-call holder K36 describes, K41's per-turn mark, and K43's +/// probe latch and replay payload. +/// +public sealed class ClarificationsTests +{ + // ----------------------------------------------------------------------------------------- + // K43: the probe latch is a compare-and-set. Several search-tool calls in one turn, or several + // graph participants sharing this call, must cost exactly one probe. + // ----------------------------------------------------------------------------------------- + [Fact] + public void ClaimProbe_ManyConcurrentCallers_ExactlyOneClaimsEachTrial() + { + // 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++) + { + 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; + + var threads = new Thread[callers]; + for (var i = 0; i < callers; i++) + { + threads[i] = new Thread(() => + { + try + { + barrier.SignalAndWait(); + if (clarifications.ClaimProbe().Won) + { + Interlocked.Increment(ref claims); + } + } + catch (Exception failure) + { + Interlocked.CompareExchange(ref escaped, failure, null); + } + }); + threads[i].Start(); + } + + foreach (var thread in threads) + { + thread.Join(); + } + + if (escaped is not null) + { + throw escaped; + } + + 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); + + var waiters = Enumerable.Range(0, 5) + .Select(_ => clarifications.ClaimProbe().WaitAsync( + TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken)) + .ToArray(); + + winner.Fail(); + + var all = Task.WhenAll(waiters); + var completed = await Task.WhenAny( + all, Task.Delay(TimeSpan.FromSeconds(2), TestContext.Current.CancellationToken)); + + Assert.Same(all, completed); + + foreach (var 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); + } + + [Fact] + public async Task Publish_LetsEveryWaiterReplayTheSameCards() + { + var clarifications = new Clarifications(); + var winner = clarifications.ClaimProbe(); + Assert.True(winner.Won); + + var waiters = Enumerable.Range(0, 3) + .Select(_ => clarifications.ClaimProbe().WaitAsync( + TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken)) + .ToArray(); + + IReadOnlyList cards = [new TextSearchProvider.TextSearchResult { Text = "note" }]; + winner.Publish(cards); + + var results = await Task.WhenAll(waiters); + + Assert.All(results, result => Assert.Same(cards, result)); + } + + // ----------------------------------------------------------------------------------------- + // K41 and K43: BeginTurn opens a fresh turn. It clears the per-turn mark and the probe latch + // and its payload together, and never the counters — those are per-call, not per-turn. + // ----------------------------------------------------------------------------------------- + [Fact] + public void BeginTurn_ClearsTheLatchAndTheMark_AndLeavesTheCounters() + { + var clarifications = new Clarifications(); + + clarifications.ClaimProbe().Publish([]); + + clarifications.Update("brand", s => + { + s.AskedThisTurn = true; + s.ProbeAsks = 3; + s.NamedAsks = 2; + s.ResetSpent = true; + }); + + clarifications.BeginTurn(); + + var brand = clarifications.Read("brand"); + Assert.False(brand.AskedThisTurn); + Assert.Equal(3, brand.ProbeAsks); + Assert.Equal(2, brand.NamedAsks); + Assert.True(brand.ResetSpent); + + // 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); + + 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); + + 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(); + + clarifications.BeginTurn(); + + Assert.True(clarifications.ClaimProbe().Won); + var loser = clarifications.ClaimProbe(); + + stale.Publish([new TextSearchProvider.TextSearchResult { Text = "turn 1" }]); + stale.Fail(); + + await Assert.ThrowsAsync( + () => loser.WaitAsync(TimeSpan.FromMilliseconds(1), TestContext.Current.CancellationToken)); + } + + // ----------------------------------------------------------------------------------------- + // Reconnect: the ask budget is per call, not per session, so what one session spent must reach + // the next one through the call's stored state. + // ----------------------------------------------------------------------------------------- + [Fact] + public void SpentAndRestoreSpent_CarryTheBudget_AndNotWhatWasNamed() + { + var first = new Clarifications(); + first.Update("applies_to", s => + { + s.ProbeAsks = 2; + s.NamedAsks = 1; + s.ResetSpent = true; + s.Pending = ["ct900", "ct900ent"]; + s.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900" }); + }); + + var spent = first.Spent(); + + var resumed = new Clarifications(); + resumed.RestoreSpent(spent); + + var slot = resumed.Read("applies_to"); + Assert.Equal(2, slot.ProbeAsks); + Assert.Equal(1, slot.NamedAsks); + Assert.True(slot.ResetSpent); + + // The pending list and what was named belong to a turn the reconnected caller is not in. + Assert.Null(slot.Pending); + Assert.Equal(Clarifications.LastNamedKind.None, slot.LastNamed.Kind); + } + + [Fact] + public void Spent_LeavesOutASlotNothingHasAskedAbout() + { + var clarifications = new Clarifications(); + clarifications.Update("brand", s => s.Pending = ["sole", "spirit"]); + + Assert.Empty(clarifications.Spent()); + } + + // ----------------------------------------------------------------------------------------- + // §7's ask is staged: reads see it at once, because step 1 and the probe's K41 skip both act on + // it this turn, but only a turn that answered the caller keeps it. + // ----------------------------------------------------------------------------------------- + [Fact] + public void Ask_IsVisibleAtOnce_ButDroppedByTheNextBeginTurn() + { + var clarifications = new Clarifications(); + var named = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900" }); + + clarifications.Ask("applies_to", named, spendsReset: false); + + var asked = clarifications.Read("applies_to"); + Assert.Equal(1, asked.NamedAsks); + Assert.True(asked.AskedThisTurn); + Assert.True(named.Names(asked.LastNamed)); + + clarifications.BeginTurn(); + + var dropped = clarifications.Read("applies_to"); + Assert.Equal(0, dropped.NamedAsks); + Assert.Equal(Clarifications.LastNamedKind.None, dropped.LastNamed.Kind); + } + + [Fact] + public void CommitAsks_KeepsTheAsk_AcrossTheTurnBoundary() + { + var clarifications = new Clarifications(); + var named = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900" }); + + clarifications.Ask("applies_to", named, spendsReset: false); + clarifications.CommitAsks(); + clarifications.BeginTurn(); + + var kept = clarifications.Read("applies_to"); + Assert.Equal(1, kept.NamedAsks); + Assert.True(named.Names(kept.LastNamed)); + } + + [Fact] + public void Ask_ThatSpendsTheReset_ReturnsTheCounterToOne() + { + var clarifications = new Clarifications(); + clarifications.Update("applies_to", s => s.NamedAsks = 3); + + clarifications.Ask("applies_to", Clarifications.LastNamed.TooMany, spendsReset: true); + + var snapshot = clarifications.Read("applies_to"); + Assert.Equal(1, snapshot.NamedAsks); + Assert.True(snapshot.ResetSpent); + } + + // ----------------------------------------------------------------------------------------- + // Edit-and-resend: Withdraw clears what was named and what is pending, and leaves the ask + // counters untouched so a withdrawn segment cannot buy a fresh maxAsks budget. + // ----------------------------------------------------------------------------------------- + [Fact] + public void Withdraw_ClearsPendingAndLastNamed_AndLeavesTheCounters() + { + var clarifications = new Clarifications(); + + clarifications.Update("brand", s => + { + s.Pending = ["ct900", "ct900ent"]; + s.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "ct900", "ct900ent" }); + s.ProbeAsks = 4; + s.NamedAsks = 1; + s.ResetSpent = true; + s.AskedThisTurn = true; + }); + + clarifications.Withdraw(); + + var after = clarifications.Read("brand"); + Assert.Null(after.Pending); + Assert.Equal(Clarifications.LastNamed.None, after.LastNamed); + Assert.Equal(4, after.ProbeAsks); + Assert.Equal(1, after.NamedAsks); + Assert.True(after.ResetSpent); + + // BeginTurn's mark is a different lifetime; Withdraw must not touch it. + Assert.True(after.AskedThisTurn); + } + + [Fact] + public void Read_ANameNeverSeenBefore_StartsAtItsZeroValues() + { + var clarifications = new Clarifications(); + + var slot = clarifications.Read("applies_to"); + + Assert.Null(slot.Pending); + Assert.Equal(Clarifications.LastNamed.None, slot.LastNamed); + Assert.Equal(0, slot.ProbeAsks); + Assert.Equal(0, slot.NamedAsks); + Assert.False(slot.ResetSpent); + Assert.False(slot.AskedThisTurn); + } + + [Fact] + public void Update_TheSameName_SharesOneUnderlyingState() + { + var clarifications = new Clarifications(); + + clarifications.Update("brand", s => s.ProbeAsks = 7); + + Assert.Equal(7, clarifications.Read("brand").ProbeAsks); + } + + // ----------------------------------------------------------------------------------------- + // §7/§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 - set the + // pending list and move a counter - reduced to its atomicity core: Pending 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; + + using var stop = new CancellationTokenSource(); + var tornObservations = 0; + + var reader = Task.Run(() => + { + while (!stop.IsCancellationRequested) + { + var snapshot = clarifications.Read(slot); + var pendingIsSet = snapshot.Pending is not null; + var probeAsksIsOdd = snapshot.ProbeAsks % 2 != 0; + + if (pendingIsSet != probeAsksIsOdd) + { + Interlocked.Increment(ref tornObservations); + } + } + }, TestContext.Current.CancellationToken); + + for (var i = 0; i < iterations; i++) + { + var opening = i % 2 == 0; + + clarifications.Update(slot, state => + { + state.Pending = opening ? ["ct900", "ct900ent"] : null; + state.ProbeAsks++; + }); + } + + await stop.CancelAsync(); + await reader; + + Assert.Equal(0, tornObservations); + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/TurnAmbientsTestScope.cs b/tests/AgentCore.Application.Tests/Runtime/TurnAmbientsTestScope.cs index 0e362614..88a485de 100644 --- a/tests/AgentCore.Application.Tests/Runtime/TurnAmbientsTestScope.cs +++ b/tests/AgentCore.Application.Tests/Runtime/TurnAmbientsTestScope.cs @@ -1,4 +1,5 @@ using AgentCore.Application.Runtime; +using Microsoft.Agents.AI; namespace AgentCore.Application.Tests.Runtime; @@ -12,5 +13,21 @@ internal static IDisposable WithSources(TurnSources sources) => TurnAmbients.Amend(ambients => ambients with { Sources = sources }); /// Opens an outer tool call over this flow. - internal static IDisposable WithOuterCall(string callId) => OuterToolCall.Enter(callId); + internal static IDisposable WithOuterCall(string callId) => OuterToolCall.Enter(callId, out _); + + /// Opens the call's ambiguity holder over this flow, the way CallSession does. + internal static IDisposable WithClarifications(Clarifications clarifications) + => TurnAmbients.Amend(ambients => ambients with { Clarifications = clarifications }); + + /// + /// Opens a turn context whose is + /// — true for a row 1 or 2 turn, false for a graph row's own participant invocation (K39). + /// + internal static IDisposable WithCarriesHistory(bool carriesHistory) + => TurnAmbients.Amend(ambients => ambients with + { + Context = new TurnContext { Session = new StubSession(), CarriesHistory = carriesHistory }, + }); + + private sealed class StubSession : AgentSession; } diff --git a/tests/AgentCore.Application.Tests/State/ExactStateValueLinkerTests.cs b/tests/AgentCore.Application.Tests/State/ExactStateValueLinkerTests.cs new file mode 100644 index 00000000..d09b6bb9 --- /dev/null +++ b/tests/AgentCore.Application.Tests/State/ExactStateValueLinkerTests.cs @@ -0,0 +1,358 @@ +using AgentCore.Application.State; +using Xunit; + +namespace AgentCore.Application.Tests.State; + +/// +/// The §12 linker table: every row asserts a claim an earlier revision of the design got wrong in +/// prose. The vocabulary and mentions are the catalogue linker_v9.py (the Python reference +/// the C# port was cross-checked against) uses, so a failure here can be compared against that +/// script directly. +/// +/// +/// Every non-ASCII literal here is a \uXXXX escape sequence, never a typed character — the same +/// rule follows, for the reason its header explains: a typed +/// decomposed character reaches disk pre-composed and the row would measure nothing. +/// +public sealed class ExactStateValueLinkerTests +{ + private static readonly HashSet NothingNamed = new(StringComparer.Ordinal); + + private static readonly string[] Catalogue = + [ + "f63", "f65", "f80", "f85", "tt8", + "ct800", "ct800ent", "ct850", "ct850ent", + "xt185", "xt285", "xt285s", "xt385", + "ct900", "ct900ent", "ctsbs900", "sole", + ]; + + private static readonly string[] Brands = ["sole", "truetread", "lifefitness"]; + + // U+0E01 is the Thai consonant ko kai; U+0E48 and U+0E49 are the mai ek and mai tho tone + // marks, both NonSpacingMark. The pair differs only by which mark it carries. + private static readonly string[] ThaiToneMarkPair = + [ + "\u0E01\u0E48900", + "\u0E01\u0E49900", + ]; + + // U+0915 is the Devanagari consonant ka; U+093E and U+094B are the aa and o vowel signs, + // both SpacingCombiningMark. + private static readonly string[] DevanagariPair = + [ + "\u0915\u093E900", + "\u0915\u094B900", + ]; + + private static readonly ExactStateValueLinker Linker = new(); + + [Fact] + public void Link_JoinedTwoTokenRun_LinksWithEmptyLastNamed() + { + var result = Linker.Link("CT900 ENT", Vocabulary(Catalogue), NothingNamed); + + AssertLinked(result, "ct900ent"); + } + + [Fact] + public void Link_ContainmentSwallowsTheShorterHit_LinksTheLongerValue() + { + var result = Linker.Link("a Sole F80", Vocabulary("f80", "solef80"), NothingNamed); + + AssertLinked(result, "solef80"); + } + + [Fact] + public void Link_DisjointSpansOfOneValue_ContainmentDoesNotRequireTheLongerHitToStartTheSame() + { + var result = Linker.Link("CT 900 ENT", Vocabulary("ct900", "900ent", "ct900ent"), NothingNamed); + + AssertLinked(result, "ct900ent"); + } + + [Fact] + public void Link_TwoDifferentIdsNamedInOneMention_IsAmbiguousNotASilentPick() + { + var result = Linker.Link("I have a CT900 and a CT900ENT", Vocabulary(Catalogue), NothingNamed); + + AssertAmbiguous(result, "ct900", "ct900ent"); + } + + [Fact] + public void Link_BareIdAloneWithEmptyLastNamed_IsAmbiguousWithItsPrefixedSibling() + { + var result = Linker.Link("CT900", Vocabulary(Catalogue), NothingNamed); + + AssertAmbiguous(result, "ct900", "ct900ent"); + } + + [Fact] + public void Link_BareIdAloneWithItselfInLastNamed_LinksIt() + { + var result = Linker.Link("CT900", Vocabulary(Catalogue), Named("ct900", "ct900ent", "ctsbs900")); + + AssertLinked(result, "ct900"); + } + + [Fact] + public void Link_UnrelatedIdWithAForeignLastNamed_LinksWithoutNeedingTheTieBreak() + { + var result = Linker.Link("an XT385", Vocabulary(Catalogue), Named("ct900", "ct900ent", "ctsbs900")); + + AssertLinked(result, "xt385"); + } + + [Fact] + public void Link_StrictPrefixHitWithEmptyLastNamed_IsAmbiguousNeverLinked() + { + var result = Linker.Link("a CT800", Vocabulary(Catalogue), NothingNamed); + + AssertAmbiguous(result, "ct800", "ct800ent"); + } + + [Fact] + public void Link_TwoNonPrefixIdsNamedTogether_IsAmbiguousWithTheSurvivingHits() + { + var result = Linker.Link("a CT900 and an XT385", Vocabulary(Catalogue), NothingNamed); + + AssertAmbiguous(result, "ct900", "xt385"); + } + + [Fact] + public void Link_NoRealIdSpelledOut_IsNoMatch() + { + var result = Linker.Link("so LE brand", Vocabulary(Catalogue), NothingNamed); + + AssertNoMatch(result); + } + + [Fact] + public void Link_CommaBreaksTheJoin_IsNoMatch() + { + var result = Linker.Link("my CT, 900 hours in", Vocabulary(Catalogue), NothingNamed); + + AssertNoMatch(result); + } + + [Fact] + public void Link_DotJoiner_Links() + { + var result = Linker.Link("CT. 900", Vocabulary(Catalogue), Named("ct900")); + + AssertLinked(result, "ct900"); + } + + [Fact] + public void Link_HyphenJoiner_Links() + { + var result = Linker.Link("CT - 900", Vocabulary(Catalogue), Named("ct900")); + + AssertLinked(result, "ct900"); + } + + [Fact] + public void Link_DoubleDotJoiner_Links() + { + var result = Linker.Link("C.T. 900", Vocabulary(Catalogue), Named("ct900")); + + AssertLinked(result, "ct900"); + } + + [Fact] + public void Link_BareConsoleWord_DoesNotFuzzyMatchSoleInsideIt() + { + var result = Linker.Link("the console is broken", Vocabulary(Catalogue), NothingNamed); + + AssertNoMatch(result); + } + + [Fact] + public void Link_ConsoleSentenceAlsoNamingSole_LinksSole() + { + var result = Linker.Link("the console is broken on my Sole", Vocabulary(Catalogue), NothingNamed); + + AssertLinked(result, "sole"); + } + + [Fact] + public void Link_DigitFreeTwoWordValue_JoinsOnTheThreeRuneRule() + { + var result = Linker.Link("a Life Fitness machine", Vocabulary(Brands), NothingNamed); + + AssertLinked(result, "lifefitness"); + } + + [Fact] + public void Link_MixedCaseVocabularyWithTieBreak_LinksTheCollectionsOwnSpelling() + { + var result = Linker.Link("a CT900", Vocabulary("CT900", "CT900ENT"), Named("CT900")); + + AssertLinked(result, "CT900"); + } + + [Fact] + public void Link_MixedCasePrefixWithNoTieBreak_CandidatesStayOrdinallySorted() + { + // "CT900ENT" sorts before "ct900" under StringComparer.Ordinal (uppercase before + // lowercase), so a bare prepend of the exact hit ahead of a separately sorted prefix list + // would leave this pair out of order. This locks in the fix. + var result = Linker.Link("a ct900", Vocabulary("ct900", "CT900ENT"), NothingNamed); + + AssertAmbiguous(result, "CT900ENT", "ct900"); + } + + [Fact] + public void Link_SpacedVocabularyValue_Links() + { + var result = Linker.Link("a CT 900", Vocabulary("CT 900"), NothingNamed); + + AssertLinked(result, "CT 900"); + } + + [Fact] + public void Link_ThaiToneMarkMentionBare_LinksItsOwnId() + { + var result = Linker.Link(ThaiToneMarkPair[0], Vocabulary(ThaiToneMarkPair), NothingNamed); + + AssertLinked(result, ThaiToneMarkPair[0]); + } + + [Fact] + public void Link_ThaiToneMarkMentionInsideASentence_LinksItsOwnId() + { + var result = Linker.Link("a " + ThaiToneMarkPair[0] + " please", Vocabulary(ThaiToneMarkPair), NothingNamed); + + AssertLinked(result, ThaiToneMarkPair[0]); + } + + [Fact] + public void Link_ThaiToneMarkMentionSpacedBeforeTheDigits_LinksItsOwnId() + { + var result = Linker.Link("\u0E01\u0E48 900", Vocabulary(ThaiToneMarkPair), NothingNamed); + + AssertLinked(result, ThaiToneMarkPair[0]); + } + + [Fact] + public void Link_TheOtherThaiToneMarkMention_DoesNotCrossLinkToItsSibling() + { + var result = Linker.Link(ThaiToneMarkPair[1], Vocabulary(ThaiToneMarkPair), NothingNamed); + + AssertLinked(result, ThaiToneMarkPair[1]); + } + + [Fact] + public void Link_DevanagariMention_LinksItsOwnId() + { + var result = Linker.Link("my " + DevanagariPair[0], Vocabulary(DevanagariPair), NothingNamed); + + AssertLinked(result, DevanagariPair[0]); + } + + [Fact] + public void BuildCandidates_SixtyTokenMention_StaysWithinTheFourTimesTokenCountBound() + { + var mention = string.Join(' ', Enumerable.Range(0, 60).Select(i => $"word{i}")); + var (tokens, separators) = VocabularyFold.Tokenize(mention); + + var candidates = ExactStateValueLinker.BuildCandidates(tokens, separators); + + Assert.Equal(60, tokens.Count); + Assert.True(candidates.Count <= 4 * 60, $"expected at most {4 * 60} candidates, got {candidates.Count}"); + Assert.Equal(234, candidates.Count); + } + + [Theory] + [InlineData(LinkOutcome.Linked, 0)] + [InlineData(LinkOutcome.Linked, 2)] + [InlineData(LinkOutcome.NoMatch, 1)] + [InlineData(LinkOutcome.Ambiguous, 1)] + public void LinkResult_ACandidateCountThatContradictsTheOutcome_IsRefused(LinkOutcome outcome, int candidates) + { + // IStateValueLinker is public, so a host linker is arbitrary code. The extractor indexes + // Candidates[0] on a Linked verdict rather than re-testing what this type already promises. + Assert.Throws( + () => new LinkResult(outcome, [.. Enumerable.Range(0, candidates).Select(i => $"v{i}")])); + } + + private static HashSet Named(params string[] values) + => new HashSet(values, StringComparer.Ordinal); + + private static VocabularyView Vocabulary(params string[] values) + { + Dictionary normalisedToOriginal = new(StringComparer.Ordinal); + foreach (var value in values) + { + normalisedToOriginal[VocabularyFold.Fold(value)] = value; + } + + return new VocabularyView { NormalisedToOriginal = normalisedToOriginal, Originals = values }; + } + + private static void AssertLinked(LinkResult result, string expected) + { + Assert.Equal(LinkOutcome.Linked, result.Outcome); + Assert.Equal([expected], result.Candidates); + } + + private static void AssertAmbiguous(LinkResult result, params string[] expectedSortedAscending) + { + Assert.Equal(LinkOutcome.Ambiguous, result.Outcome); + Assert.Equal(expectedSortedAscending, result.Candidates); + } + + private static void AssertNoMatch(LinkResult result) + { + Assert.Equal(LinkOutcome.NoMatch, result.Outcome); + Assert.Empty(result.Candidates); + } +} + +/// +/// : the name-keyed registry K12 asks for, always seeded with +/// exact. +/// +public sealed class StateValueLinkersTests +{ + [Fact] + public void Resolve_Exact_ReturnsTheBuiltInLinker() + { + var registry = new StateValueLinkers([]); + + var linker = registry.Resolve("exact"); + + Assert.IsType(linker); + } + + [Fact] + public void Names_AlwaysIncludesExactEvenWithNoHostLinkers() + { + var registry = new StateValueLinkers([]); + + Assert.Contains("exact", registry.Names); + } + + [Fact] + public void Resolve_AnUnregisteredName_Throws() + { + var registry = new StateValueLinkers([]); + + Assert.Throws(() => registry.Resolve("bogus")); + } + + [Fact] + public void Constructor_TwoHostLinkersShareAName_Throws() + => Assert.Throws(() => new StateValueLinkers( + [ + new NamedLinker("custom"), + new NamedLinker("custom"), + ])); + + private sealed class NamedLinker(string name) : IStateValueLinker + { + public string Name { get; } = name; + + public LinkResult Link(string mention, VocabularyView vocabulary, IReadOnlySet lastNamed) + => throw new NotSupportedException(); + } +} diff --git a/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs b/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs index 27b643f6..786390da 100644 --- a/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs +++ b/tests/AgentCore.Application.Tests/State/StateDocumentTests.cs @@ -60,6 +60,31 @@ public sealed class StateDocumentTests }, }; + private static AgentCoreConfiguration WithVocabularySlot() => new() + { + ApiVersion = "agentcore/v1", + Name = "doc", + State = new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = new() + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + Vocabulary = new SlotVocabularyConfiguration { From = "knowledge" }, + }, + }, + }; + + private static Dictionary VocabularyOf(params string[] originals) + => new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = new VocabularyView + { + NormalisedToOriginal = originals.ToDictionary(VocabularyFold.Fold, StringComparer.Ordinal), + Originals = originals, + }, + }; + [Fact] public void TryWrite_ValueOutsideTheEnum_IsRefused() { @@ -88,6 +113,24 @@ public void TryWrite_ValueInsideTheEnum_IsAccepted() Assert.Equal("f65", state.Read("applies_to")?.GetValue()); } + [Fact] + public void TryWrite_ValueOutsideTheVocabularySnapshot_IsRefused() + { + var state = new StateDocument(WithVocabularySlot(), vocabulary: VocabularyOf("f63", "f65")); + + Assert.False(state.TryWrite("applies_to", JsonValue.Create("f80"))); + Assert.True(state.IsUnfilled("applies_to")); + } + + [Fact] + public void TryWrite_ValueInsideTheVocabularySnapshot_IsAccepted() + { + var state = new StateDocument(WithVocabularySlot(), vocabulary: VocabularyOf("f63", "f65")); + + Assert.True(state.TryWrite("applies_to", JsonValue.Create("f65"))); + Assert.Equal("f65", state.Read("applies_to")?.GetValue()); + } + [Fact] public void WrittenSlots_HandsOutAFreshCopyEveryCall() { diff --git a/tests/AgentCore.Application.Tests/State/StateExtractorLinkerTests.cs b/tests/AgentCore.Application.Tests/State/StateExtractorLinkerTests.cs new file mode 100644 index 00000000..0e610544 --- /dev/null +++ b/tests/AgentCore.Application.Tests/State/StateExtractorLinkerTests.cs @@ -0,0 +1,299 @@ +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Runtime; +using AgentCore.Application.State; +using AgentCore.Application.Tests.Fakes; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.State; + +/// +/// The gate and the linker in the extractor path (design §6): what StateExtractor.Write does +/// with a vocabulary: slot's free-text answer, and the K19 guarantee that nothing changes for +/// a document that declares none. +/// +public sealed class StateExtractorLinkerTests +{ + private const string VocabularyYaml = + """ + apiVersion: agentcore/v1 + name: linker + state: + applies_to: { type: string, writer: extractor, vocabulary: { from: knowledge } } + brand: { type: string, writer: extractor, enum: [f80, f65] } + extractor: + model: { ref: fill } + when: after_reply + agents: + items: + - { id: only } + """; + + private const string UnknownLinkerYaml = + """ + apiVersion: agentcore/v1 + name: unknown-linker + state: + applies_to: { type: string, writer: extractor, vocabulary: { from: knowledge, linker: mine } } + extractor: + model: { ref: fill } + when: after_reply + agents: + items: + - { id: only } + """; + + private const string NoVocabularyYaml = + """ + apiVersion: agentcore/v1 + name: no-vocabulary + state: + callerSaidGoodbye: { type: boolean, default: false, writer: extractor } + extractor: + model: { ref: fill } + when: after_reply + agents: + items: + - { id: only } + """; + + private static readonly AgentCoreConfiguration VocabularyDocument = ConfigurationLoader.LoadYaml(VocabularyYaml); + + private static readonly AgentCoreConfiguration NoVocabularyDocument = ConfigurationLoader.LoadYaml(NoVocabularyYaml); + + private static readonly AgentCoreConfiguration UnknownLinkerDocument = ConfigurationLoader.LoadYaml(UnknownLinkerYaml); + + [Fact] + public void ALinkedOutcome_WritesTheCollectionsSpelling() + { + var (extractor, state, clarifications) = Build("CT900", "CT900ENT"); + + var result = extractor.Write(state, """{ "applies_to": "the CT900ENT" }""", clarifications); + + Assert.Equal(1, result.Filled); + Assert.Equal("CT900ENT", state.Read("applies_to")?.GetValue()); + } + + [Fact] + public void AnAmbiguousOutcome_LeavesTheSlotUnfilledAndSetsThePendingList() + { + var (extractor, state, clarifications) = Build("CT900", "CT900ENT"); + + var result = extractor.Write(state, """{ "applies_to": "the CT900" }""", clarifications); + + Assert.True(state.IsUnfilled("applies_to")); + Assert.Equal(0, result.Filled); + Assert.Equal(["CT900", "CT900ENT"], clarifications.Read("applies_to").Pending); + } + + [Fact] + public void APendingListAlreadySetByAnotherChannel_ANoMatchLeavesItAlone() + { + var (extractor, state, clarifications) = Build("CT900", "CT900ENT"); + clarifications.Update("applies_to", s => s.Pending = ["OTHER1", "OTHER2"]); + + extractor.Write(state, """{ "applies_to": "the elliptical machine" }""", clarifications); + + // NoMatch does nothing at all — the pending list survives untouched. + Assert.Equal(["OTHER1", "OTHER2"], clarifications.Read("applies_to").Pending); + Assert.True(state.IsUnfilled("applies_to")); + } + + [Fact] + public void AnAmbiguousOutcome_OverwritesAnExistingPendingListWithTheNewNearTie() + { + var (extractor, state, clarifications) = Build("CT900", "CT900ENT", "CT850", "CT850ENT"); + clarifications.Update("applies_to", s => s.Pending = ["CT900", "CT900ENT"]); + + extractor.Write(state, """{ "applies_to": "the CT850" }""", clarifications); + + // A caller who near-ties a second, different pair must not be silently dropped because + // the first pair is still sitting unresolved: extraction runs after_reply, so this is the + // caller's own later words beating whatever was pending (§7's recovery path). + Assert.True(state.IsUnfilled("applies_to")); + Assert.Equal(["CT850", "CT850ENT"], clarifications.Read("applies_to").Pending); + } + + [Fact] + public void ANoMatchOutcome_LeavesTheSlotAndThePendingListAlone() + { + var (extractor, state, clarifications) = Build("CT900", "CT900ENT"); + + var result = extractor.Write(state, """{ "applies_to": "the elliptical machine" }""", clarifications); + + Assert.True(state.IsUnfilled("applies_to")); + Assert.Equal(0, result.Filled); + Assert.Null(clarifications.Read("applies_to").Pending); + } + + [Fact] + public void AWrittenSlot_NamedAgainByItsShorterPrefix_IsHeardAsANearTie_NotOverwritten() + { + var (extractor, state, clarifications) = Build("CT900", "CT900ENT"); + + // Simulates a prior ask that named both candidates. Left in place, this would let the + // tie-break in §6 step 4 fire on the second mention and silently replace the caller's + // confirmed machine — exactly the bug K30's clear exists to prevent. + clarifications.Update( + "applies_to", + slot => slot.LastNamed = Clarifications.LastNamed.Of( + new HashSet(StringComparer.Ordinal) { "CT900", "CT900ENT" })); + + extractor.Write(state, """{ "applies_to": "the CT900ENT" }""", clarifications); + + Assert.Equal("CT900ENT", state.Read("applies_to")?.GetValue()); + Assert.Equal(Clarifications.LastNamedKind.None, clarifications.Read("applies_to").LastNamed.Kind); + + extractor.Write(state, """{ "applies_to": "the CT900" }""", clarifications); + + // Ambiguous, not Linked: LastNamed was cleared by the write above, so the shorter mention + // cannot tie-break and the filled slot stands. + Assert.Equal("CT900ENT", state.Read("applies_to")?.GetValue()); + Assert.Equal(["CT900", "CT900ENT"], clarifications.Read("applies_to").Pending); + } + + [Fact] + public void AnEnumOnlySlot_ASuccessfulWrite_ClearsItsPendingListAndLastNamed() + { + // K30 is unconditional over every slot StateExtractor.Write iterates, enum:-only slots + // included — not just the vocabulary: slots the linker touches. "brand" has a hand-written + // enum: and never sees a linker (§6's closing paragraph), so this is the one channel that + // can ever populate its Pending/LastNamed: a probe or a prior ask, simulated here directly. + var (extractor, state, clarifications) = Build("CT900", "CT900ENT"); + + clarifications.Update("brand", slot => + { + slot.Pending = ["f80", "f65"]; + slot.LastNamed = Clarifications.LastNamed.Of(new HashSet(StringComparer.Ordinal) { "f80", "f65" }); + }); + + extractor.Write(state, """{ "brand": "f80" }""", clarifications); + + Assert.Equal("f80", state.Read("brand")?.GetValue()); + Assert.Null(clarifications.Read("brand").Pending); + Assert.Equal(Clarifications.LastNamedKind.None, clarifications.Read("brand").LastNamed.Kind); + } + + [Fact] + public void ANonStringAnswerToAVocabularySlot_StillGoesThroughTheLinker() + { + // The schema asks for a string, but nothing stops a model answering the bare number. Coerced + // straight to "900" it would pass the gate, because "900" is a member — silently picking one + // side of the near-tie the linker exists to refuse. + var (extractor, state, clarifications) = Build("900", "900ENT"); + + var result = extractor.Write(state, """{ "applies_to": 900 }""", clarifications); + + Assert.True(state.IsUnfilled("applies_to")); + Assert.Equal(0, result.Filled); + Assert.Equal(["900", "900ENT"], clarifications.Read("applies_to").Pending); + } + + [Fact] + public void ALinkerThatThrows_RefusesTheSlotAndNotTheTurn() + { + var client = new ScriptedChatClient("{}"); + var extractor = new StateExtractor(UnknownLinkerDocument, client, new StateValueLinkers([])); + var state = new StateDocument( + UnknownLinkerDocument, + vocabulary: new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = ViewOf("CT900"), + }); + + // "mine" is registered nowhere, so Resolve throws. Section 8.7: that must cost the slot, not + // the call. + var result = extractor.Write(state, """{ "applies_to": "the CT900" }""", new Clarifications()); + + Assert.True(result.Deserialized); + Assert.Equal(1, result.Rejected); + Assert.True(state.IsUnfilled("applies_to")); + } + + [Fact] + public async Task NoVocabularySlot_TheRequestIsByteIdenticalThroughTheInternalOverload() + { + RecordingChatClient viaPublicApi = new("""{ "callerSaidGoodbye": null }"""); + StateExtractor publicExtractor = new(NoVocabularyDocument, viaPublicApi); + + await publicExtractor.ExtractAsync( + new StateDocument(NoVocabularyDocument), + [new ChatMessage(ChatRole.User, "hello")], + TestContext.Current.CancellationToken); + + RecordingChatClient viaInternalApi = new("""{ "callerSaidGoodbye": null }"""); + StateExtractor internalExtractor = new(NoVocabularyDocument, viaInternalApi, new StateValueLinkers([])); + + await internalExtractor.ExtractAsync( + new StateDocument(NoVocabularyDocument), + [new ChatMessage(ChatRole.User, "hello")], + new Clarifications(), + TestContext.Current.CancellationToken); + + Assert.NotNull(viaPublicApi.LastMessages); + Assert.NotNull(viaInternalApi.LastMessages); + Assert.Equal(Render(viaPublicApi.LastMessages!), Render(viaInternalApi.LastMessages!)); + } + + private static string Render(IEnumerable messages) + => string.Join('\u001e', messages.Select(message => $"{message.Role}\u001f{message.Text}")); + + private static ( + StateExtractor Extractor, + StateDocument State, + Clarifications Clarifications) Build(params string[] vocabularyValues) + { + var client = new ScriptedChatClient("{}"); + var extractor = new StateExtractor(VocabularyDocument, client, new StateValueLinkers([])); + var vocabulary = new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = ViewOf(vocabularyValues), + }; + var state = new StateDocument(VocabularyDocument, vocabulary: vocabulary); + + return (extractor, state, new Clarifications()); + } + + private static VocabularyView ViewOf(params string[] originals) + { + Dictionary normalisedToOriginal = new(StringComparer.Ordinal); + foreach (var original in originals) + { + normalisedToOriginal[VocabularyFold.Fold(original)] = original; + } + + return new VocabularyView { NormalisedToOriginal = normalisedToOriginal, Originals = originals }; + } + + private sealed class RecordingChatClient : IChatClient + { + private readonly string _reply; + + public RecordingChatClient(string reply) => _reply = reply; + + public IReadOnlyList? LastMessages { get; private set; } + + public Task GetResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + { + LastMessages = [.. messages]; + return Task.FromResult(new ChatResponse(new ChatMessage(ChatRole.Assistant, _reply))); + } + + public IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + CancellationToken cancellationToken = default) + => throw new NotSupportedException("StateExtractor never streams."); + + public object? GetService(Type serviceType, object? serviceKey = null) => null; + + public void Dispose() + { + // Nothing to release. + } + } +} diff --git a/tests/AgentCore.Application.Tests/State/VocabularyCacheTests.cs b/tests/AgentCore.Application.Tests/State/VocabularyCacheTests.cs new file mode 100644 index 00000000..5156f2d2 --- /dev/null +++ b/tests/AgentCore.Application.Tests/State/VocabularyCacheTests.cs @@ -0,0 +1,288 @@ +using System.Collections.Concurrent; +using AgentCore.Application.State; +using AgentCore.TestSupport; +using Xunit; + +namespace AgentCore.Application.Tests.State; + +/// +/// : the per-slot immutable vocabulary, and 's +/// section 10 refusals. +/// +public sealed class VocabularyCacheTests +{ + [Fact] + public void Replace_ZeroValues_ThrowsNamingTheSlot() + { + var cache = new VocabularyCache(); + + var exception = Assert.Throws(() => cache.Replace("machine", [], maxValues: 100)); + + Assert.Equal("machine", exception.Slot); + } + + [Fact] + public void Replace_OnlyTheWildcardValue_ThrowsAsZeroValuesAfterStripping() + { + var cache = new VocabularyCache(); + + Assert.Throws( + () => cache.Replace("machine", ["*"], maxValues: 100, wildcardValue: "*")); + } + + [Fact] + public void Replace_CountEqualsMaxValues_ThrowsBecauseATruncationCannotBeToldFromACompleteRead() + { + var cache = new VocabularyCache(); + + Assert.Throws(() => cache.Replace("machine", ["a", "b"], maxValues: 2)); + } + + [Fact] + public void Replace_CountExceedsMaxValues_StillThrows() + { + // K4's own truncation check is a rank cut against maxValues, not an exact-count comparison: + // a store that ignored its own limit and returned more than maxValues must not slip past it. + var cache = new VocabularyCache(); + + Assert.Throws(() => cache.Replace("machine", ["a", "b", "c"], maxValues: 2)); + } + + [Fact] + public void Replace_TwoValuesFoldAlike_ThrowsNamingBoth() + { + var cache = new VocabularyCache(); + + var exception = Assert.Throws( + () => cache.Replace("machine", ["T900", "t900"], maxValues: 100)); + + Assert.Contains("T900", exception.Message, StringComparison.Ordinal); + Assert.Contains("t900", exception.Message, StringComparison.Ordinal); + } + + [Fact] + public void Replace_ValueFoldsToEmpty_ThrowsAndDoesNotDependOnComposition() + { + // "***" has nothing for NFC to compose and nothing for Keep to keep, so this refusal + // fires identically whether or not the runtime can compose Unicode (K44 governs + // composition; this row exercises the K31/K46 refusal on its own). + var cache = new VocabularyCache(); + + var exception = Assert.Throws( + () => cache.Replace("machine", ["***"], maxValues: 100)); + + Assert.Contains("***", exception.Message, StringComparison.Ordinal); + } + + [Fact] + public void Replace_WildcardValueStripped_DoesNotFalselyTriggerTheFoldsToEmptyRefusal() + { + // If "*" were not removed before the empty-fold check (K6), it would fold to "" itself + // and wrongly refuse startup on a document that is otherwise perfectly fine. + var cache = new VocabularyCache(); + + cache.Replace("machine", ["*", "T900"], maxValues: 100, wildcardValue: "*"); + + var view = cache.Snapshot()["machine"]; + Assert.Equal(["T900"], view.Originals); + } + + [Fact] + public void Replace_WildcardValueFoldsLikeASurvivor_DoesNotFalselyTriggerTheFoldingCollisionRefusal() + { + // K6: the wildcard is stripped before the *collision* check specifically, not only before + // the empty-fold check. "ALL" and "all" fold alike, so if the strip ran after the collision + // check (or not at all), the untouched wildcard sentinel "ALL" would collide with the real + // survivor "all" and Replace would wrongly refuse a document that is otherwise fine. + var cache = new VocabularyCache(); + + cache.Replace("machine", ["ALL", "all"], maxValues: 100, wildcardValue: "ALL"); + + var view = cache.Snapshot()["machine"]; + Assert.Equal(["all"], view.Originals); + } + + [Fact] + public void Replace_MixedCaseSpacedHyphenatedValue_MapsBackToTheOriginal() + { + var cache = new VocabularyCache(); + + cache.Replace("machine", ["North-900 Pro"], maxValues: 100); + + var view = cache.Snapshot()["machine"]; + var normalised = VocabularyFold.Fold("North-900 Pro"); + Assert.Equal("North-900 Pro", view.NormalisedToOriginal[normalised]); + } + + [Fact] + public void Replace_ExactlyOneValue_Succeeds() + { + var cache = new VocabularyCache(); + + cache.Replace("machine", ["T900"], maxValues: 100); + + Assert.Equal(["T900"], cache.Snapshot()["machine"].Originals); + } + + [Fact] + public void Snapshot_TakenBeforeReplace_IsUnaffectedByALaterReplace() + { + var cache = new VocabularyCache(); + cache.Replace("machine", ["T900"], maxValues: 100); + + var before = cache.Snapshot(); + var viewBefore = before["machine"]; + cache.Replace("machine", ["F80"], maxValues: 100); + var after = cache.Snapshot(); + + // "Byte-identical" (the acceptance clause's word) means the same object, not merely an + // equal one: Replace swaps the outer dictionary reference rather than mutating an entry, + // so the view a caller already read must never change under it. + Assert.Same(viewBefore, before["machine"]); + Assert.NotSame(before, after); + Assert.Equal(["T900"], before["machine"].Originals); + Assert.Equal(["F80"], after["machine"].Originals); + } + + [Fact] + public void Snapshot_BeforeAnyReplace_HasNoEntryForTheSlot() + { + var cache = new VocabularyCache(); + + Assert.False(cache.Snapshot().ContainsKey("machine")); + } + + [Fact] + public void LastGoodAt_BeforeAnyReplace_IsNull() + { + var cache = new VocabularyCache(); + + Assert.Null(cache.LastGoodAt("machine")); + } + + [Fact] + public void LastGoodAt_AfterAReplace_IsTheClocksTime() + { + var clock = new FakeTimeProvider(DateTimeOffset.Parse("2026-09-02T12:00:00Z", System.Globalization.CultureInfo.InvariantCulture)); + var cache = new VocabularyCache(clock); + + cache.Replace("machine", ["T900"], maxValues: 100); + + Assert.Equal(clock.GetUtcNow(), cache.LastGoodAt("machine")); + } + + [Fact] + public async Task Snapshot_ReadWhileARefreshIsReplacing_NeverThrows() + { + var cache = new VocabularyCache(); + cache.Replace("machine", ["T900"], maxValues: 100); + + using ManualResetEventSlim reading = new(); + using CancellationTokenSource stop = new(); + + var reader = Task.Run( + () => + { + reading.Set(); + while (!stop.IsCancellationRequested) + { + var snapshot = cache.Snapshot(); + _ = snapshot["machine"].Originals.Count; + } + }, + TestContext.Current.CancellationToken); + + reading.Wait(TestContext.Current.CancellationToken); + + for (var round = 0; round < 200; round++) + { + cache.Replace("machine", [round % 2 == 0 ? "T900" : "F80"], maxValues: 100); + } + + await stop.CancelAsync(); + await reader; + } + + [Fact] + public async Task Replace_TwoThreadsRacingTheSameSlot_SnapshotAndLastGoodAtAgreeOnTheLastWriter() + { + // Replace writes the new view and the new LastGoodAt inside one lock. If that regressed to + // two separate critical sections, a thread whose GetUtcNow() call landed after a later + // thread's view swap could leave Snapshot() and LastGoodAt() naming two different writes. + // + // Which thread's write is "last" is otherwise unobservable from outside the lock, so + // TaggingTimeProvider records, on every clock read, which value this thread is currently + // writing. Because GetUtcNow() only ever runs from inside Replace's own lock, the recorded + // ticks reconstruct the true lock-acquisition order regardless of how the OS scheduled the + // two threads — the assertion does not depend on which thread physically ran last. + const int Rounds = 300; + var timeout = TimeSpan.FromSeconds(10); + var provider = new TaggingTimeProvider(); + var cache = new VocabularyCache(provider); + + using ManualResetEventSlim start = new(); + + // Two barriers, not one: startOfRound re-synchronises both threads before either writes, + // so neither can pull ahead and finish its own tail alone — every round has both threads + // genuinely contending for the lock at close to the same instant. afterWrites re-joins them + // once both threads' Replace calls for the round have returned, which is a quiescent point — + // no writer is in flight and neither thread can start the next round's Replace until this + // phase's post-action returns — so the invariant can be checked here every round instead of + // only once at the very end, where it only ever exercised the last round's own timing. + using Barrier startOfRound = new(2); + using Barrier afterWrites = new(2, _ => AssertQuiescentAgreement(provider, cache)); + + void RaceWithTag(string prefix) + { + start.Wait(); + for (var index = 0; index < Rounds; index++) + { + Assert.True(startOfRound.SignalAndWait(timeout), "Timed out starting a round."); + + var value = prefix + index.ToString(System.Globalization.CultureInfo.InvariantCulture); + TaggingTimeProvider.Tag(value); + cache.Replace("machine", [value], maxValues: 1_000_000); + + // If Replace ever threw, this thread would never reach here and the other thread + // would otherwise wait forever for a partner that is not coming — the timeout turns + // that into a failed assertion instead of a hung test. + Assert.True(afterWrites.SignalAndWait(timeout), "Timed out at the round's quiescent checkpoint."); + } + } + + var threadA = Task.Run(() => RaceWithTag("A"), TestContext.Current.CancellationToken); + var threadB = Task.Run(() => RaceWithTag("B"), TestContext.Current.CancellationToken); + start.Set(); + await Task.WhenAll(threadA, threadB); + + Assert.Equal(Rounds * 2, provider.Calls.Count); + } + + private static void AssertQuiescentAgreement(TaggingTimeProvider provider, VocabularyCache cache) + { + var last = provider.Calls.OrderByDescending(call => call.At).First(); + + Assert.Equal([last.Value], cache.Snapshot()["machine"].Originals); + Assert.Equal(last.At, cache.LastGoodAt("machine")); + } + + private sealed class TaggingTimeProvider : TimeProvider + { + [ThreadStatic] + private static string? _currentValue; + + private readonly ConcurrentQueue<(string Value, DateTimeOffset At)> _calls = new(); + private long _ticks; + + public IReadOnlyList<(string Value, DateTimeOffset At)> Calls => [.. _calls]; + + public static void Tag(string value) => _currentValue = value; + + public override DateTimeOffset GetUtcNow() + { + var at = DateTimeOffset.UnixEpoch.AddTicks(Interlocked.Increment(ref _ticks)); + _calls.Enqueue((_currentValue ?? string.Empty, at)); + return at; + } + } +} diff --git a/tests/AgentCore.Application.Tests/State/VocabularyFoldTests.cs b/tests/AgentCore.Application.Tests/State/VocabularyFoldTests.cs new file mode 100644 index 00000000..007816dc --- /dev/null +++ b/tests/AgentCore.Application.Tests/State/VocabularyFoldTests.cs @@ -0,0 +1,112 @@ +using AgentCore.Application.State; +using Xunit; + +namespace AgentCore.Application.Tests.State; + +/// +/// : the K31 fold, and the tokeniser that shares its predicate. +/// +/// +/// Every non-ASCII literal here is a \uXXXX / \UXXXXXXXX escape sequence, never a typed +/// character. Round 12 of the design's review wrote a decomposed probe input as typed characters, +/// which an editor or a file-writing tool had already re-composed on disk, so the check silently +/// measured nothing. This file is written the same way for every row. +/// +/// Rows that hold only where the runtime composes Unicode live in +/// AgentCore.Application.Unicode.Tests instead. This project runs under the repo-wide +/// InvariantGlobalization=true that production ships, where NFC composition is a no-op. +/// +/// +public sealed class VocabularyFoldTests +{ + [Fact] + public void Fold_LetterWithRingAboveVsPlainLetter_DoesNotCollide() + { + var withRing = VocabularyFold.Fold("\u00C5T900"); + var plain = VocabularyFold.Fold("T900"); + + Assert.NotEqual(withRing, plain); + } + + [Fact] + public void Fold_SharpSVsDoubleS_DoesNotCollide() + { + var sharpS = VocabularyFold.Fold("\u00DFf80"); + var doubleS = VocabularyFold.Fold("SSF80"); + + Assert.NotEqual(sharpS, doubleS); + } + + [Fact] + public void Fold_ThaiToneMarkPresentVsAbsent_DoesNotCollide() + { + // \u0E01 is the Thai consonant ko kai; \u0E48 is the mai ek tone mark, a + // NonSpacingMark. K31 keeps marks rather than stripping them. + var withToneMark = VocabularyFold.Fold("\u0E01\u0E48"); + var withoutToneMark = VocabularyFold.Fold("\u0E01"); + + Assert.NotEqual(withToneMark, withoutToneMark); + } + + [Fact] + public void Fold_TwoAstralLetters_StayDistinct() + { + // \U0001D400 and \U0001D401 are astral (supplementary-plane) mathematical capital letters. + // char-based iteration would see two lone surrogate halves per id, both classified + // UnicodeCategory.Surrogate and so dropped by Keep, collapsing both ids to "id" and + // colliding them. Rune-based iteration reads one codepoint, correctly classified Lu. + var first = VocabularyFold.Fold("id\U0001D400"); + var second = VocabularyFold.Fold("id\U0001D401"); + + Assert.NotEqual(first, second); + } + + [Fact] + public void Fold_PunctuationOnlyValue_IsEmpty() + { + Assert.Equal(string.Empty, VocabularyFold.Fold("***")); + } + + [Fact] + public void Fold_MixedCaseSpacedHyphenatedValue_DropsSeparatorsAndLowersCase() + { + Assert.Equal("north900pro", VocabularyFold.Fold("North-900 Pro")); + } + + [Fact] + public void Tokenize_SpacedHyphenatedMention_DropsLeadingAndTrailingSeparators() + { + var (tokens, separators) = VocabularyFold.Tokenize(" north-900 pro "); + + Assert.Equal(["north", "900", "pro"], tokens); + Assert.Equal(["-", " "], separators); + } + + [Fact] + public void Tokenize_TokensConcatenated_EqualFoldOfTheWholeMention() + { + const string Mention = " North-900 \u00C5Pro!! "; + + var (tokens, _) = VocabularyFold.Tokenize(Mention); + + Assert.Equal(VocabularyFold.Fold(Mention), string.Concat(tokens)); + } + + [Fact] + public void Tokenize_NoKeptRunes_ReturnsNoTokensAndNoSeparators() + { + var (tokens, separators) = VocabularyFold.Tokenize("!!! ---"); + + Assert.Empty(tokens); + Assert.Empty(separators); + } + + [Fact] + public void Tokenize_OneTokenNoSeparators_ReturnsOneTokenAndNoSeparators() + { + var (tokens, separators) = VocabularyFold.Tokenize("T900"); + + Assert.Equal(["t900"], tokens); + Assert.Empty(separators); + } +} diff --git a/tests/AgentCore.Application.Unicode.Tests/.editorconfig b/tests/AgentCore.Application.Unicode.Tests/.editorconfig new file mode 100644 index 00000000..3d6eebe7 --- /dev/null +++ b/tests/AgentCore.Application.Unicode.Tests/.editorconfig @@ -0,0 +1,5 @@ +[*.cs] + +# CA1707: "Remove the underscores from member name". A test name reads Subject_Behaviour, and the +# underscore is what separates the two halves. +dotnet_diagnostic.CA1707.severity = none diff --git a/tests/AgentCore.Application.Unicode.Tests/AgentCore.Application.Unicode.Tests.csproj b/tests/AgentCore.Application.Unicode.Tests/AgentCore.Application.Unicode.Tests.csproj new file mode 100644 index 00000000..4812ed15 --- /dev/null +++ b/tests/AgentCore.Application.Unicode.Tests/AgentCore.Application.Unicode.Tests.csproj @@ -0,0 +1,28 @@ + + + + false + true + + false + + + + + + + + + + + + + diff --git a/tests/AgentCore.Application.Unicode.Tests/State/VocabularyFoldCompositionTests.cs b/tests/AgentCore.Application.Unicode.Tests/State/VocabularyFoldCompositionTests.cs new file mode 100644 index 00000000..8c8a95ce --- /dev/null +++ b/tests/AgentCore.Application.Unicode.Tests/State/VocabularyFoldCompositionTests.cs @@ -0,0 +1,39 @@ +using System.Text; +using AgentCore.Application.State; +using Xunit; + +namespace AgentCore.Application.Unicode.Tests.State; + +/// +/// The claims that hold only where the runtime composes Unicode. They +/// live in this project rather than beside the rest of the fold's rows because it is the one that +/// sets InvariantGlobalization=false; under the repo-wide true that production ships, +/// NFC is a no-op and both rows below would fail. +/// +/// +/// Every non-ASCII literal here is a \uXXXX escape sequence, never a typed character. Round 12 of +/// the design's review wrote a decomposed probe input as typed characters, which an editor or a +/// file-writing tool had already re-composed on disk, so the check silently measured nothing. +/// +public sealed class VocabularyFoldCompositionTests +{ + [Fact] + public void Fold_DecomposedAndComposedSpellingsOfOneValue_Collide() + { + // U+0041 U+030A is "A" followed by a combining ring above (NFD); U+00C5 is the precomposed + // Angstrom sign (NFC). NFC composition is what makes the two fold alike. + var decomposed = VocabularyFold.Fold("\u0041\u030A900"); + var composed = VocabularyFold.Fold("\u00C5900"); + + Assert.Equal(composed, decomposed); + } + + [Fact] + public void Probe_DecomposedARing_ComposesUnderThisProjectsIcu() + { + // The exact K44 boot probe (design doc section 10). Its counterpart in + // AgentCore.AspNetCore.Tests asserts the opposite under that project's invariant runtime, + // so the pair pins both sides of the condition K44 branches on. + Assert.Equal("\u00C5", "\u0041\u030A".Normalize(NormalizationForm.FormC)); + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs new file mode 100644 index 00000000..3c8dea9e --- /dev/null +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs @@ -0,0 +1,743 @@ +using System.Text.Json.Nodes; +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.Application.State; +using AgentCore.AspNetCore.DependencyInjection; +using AgentCore.AspNetCore.Tests.Fakes; +using AgentCore.Domain.Knowledge; +using AgentCore.TestSupport; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging.Abstractions; +using Microsoft.Extensions.Options; +using Xunit; + +namespace AgentCore.AspNetCore.Tests.DependencyInjection; + +/// +/// Task A7: section 10's boot read of every vocabulary: slot, K44's Unicode probe, and K48's +/// per-wildcard-facet * check — all made in . +/// +public sealed class VocabularyStartupTests +{ + [Fact] + public async Task ApplyVocabularyAsync_ZeroValues_FailsNamingTheSlotAndPath() + { + var configuration = Configuration([("brand", Vocabulary(maxValues: 10))]); + FakeFacetPort port = new(); + VocabularyCache cache = new(); + + var failure = await Assert.ThrowsAsync( + () => KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, NullLogger.Instance, TestContext.Current.CancellationToken, + composesUnicode: () => true).AsTask()); + + var error = Assert.Single(failure.Errors); + Assert.Contains("brand", error.Message, StringComparison.Ordinal); + Assert.Contains("facets.brand", error.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task ApplyVocabularyAsync_ExactlyMaxValues_FailsAsTruncated() + { + var configuration = Configuration([("brand", Vocabulary(maxValues: 3))]); + var port = new FakeFacetPort().With("facets.brand", "acme", "globex", "initech"); + VocabularyCache cache = new(); + + var failure = await Assert.ThrowsAsync( + () => KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, NullLogger.Instance, TestContext.Current.CancellationToken, + composesUnicode: () => true).AsTask()); + + var error = Assert.Single(failure.Errors); + Assert.Contains("3", error.Message, StringComparison.Ordinal); + Assert.Contains("brand", error.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task ApplyVocabularyAsync_TwoValuesFoldAlike_FailsNamingBoth() + { + var configuration = Configuration([("brand", Vocabulary(maxValues: 10))]); + var port = new FakeFacetPort().With("facets.brand", "Acme", "ACME"); + VocabularyCache cache = new(); + + var failure = await Assert.ThrowsAsync( + () => KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, NullLogger.Instance, TestContext.Current.CancellationToken, + composesUnicode: () => true).AsTask()); + + var error = Assert.Single(failure.Errors); + Assert.Contains("Acme", error.Message, StringComparison.Ordinal); + Assert.Contains("ACME", error.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task ApplyVocabularyAsync_ExactlyOneValue_SucceedsAndWarns() + { + var configuration = Configuration([("brand", Vocabulary(maxValues: 10))]); + var port = new FakeFacetPort().With("facets.brand", "acme"); + VocabularyCache cache = new(); + RecordingLoggerFactory loggers = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, loggers.CreateLogger("test"), TestContext.Current.CancellationToken, + composesUnicode: () => true); + + Assert.Equal(["acme"], cache.Snapshot()["brand"].Originals); + var line = Assert.Single(loggers.Of(1)); + Assert.Equal(Microsoft.Extensions.Logging.LogLevel.Warning, line.Level); + Assert.Equal("brand", line.Field("Slot")); + } + + [Fact] + public async Task ApplyVocabularyAsync_NonComposingRuntimeWithoutAssumeNormalized_FailsNamingInvariantGlobalization() + { + var configuration = Configuration([("brand", Vocabulary(maxValues: 10, assumeNormalized: false))]); + var port = new FakeFacetPort().With("facets.brand", "acme", "globex"); + VocabularyCache cache = new(); + + var failure = await Assert.ThrowsAsync( + () => KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, NullLogger.Instance, TestContext.Current.CancellationToken, + composesUnicode: () => false).AsTask()); + + var error = Assert.Single(failure.Errors); + Assert.Contains("InvariantGlobalization", error.Message, StringComparison.Ordinal); + Assert.Contains("brand", error.Message, StringComparison.Ordinal); + Assert.Empty(port.Reads); + } + + [Fact] + public async Task ApplyVocabularyAsync_NonComposingRuntimeWithAssumeNormalized_Succeeds() + { + var configuration = Configuration([("brand", Vocabulary(maxValues: 10, assumeNormalized: true))]); + var port = new FakeFacetPort().With("facets.brand", "acme", "globex"); + VocabularyCache cache = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, NullLogger.Instance, TestContext.Current.CancellationToken, + composesUnicode: () => false); + + Assert.Equal(["acme", "globex"], cache.Snapshot()["brand"].Originals); + } + + [Fact] + public async Task ApplyVocabularyAsync_ComposingRuntime_Succeeds() + { + var configuration = Configuration([("brand", Vocabulary(maxValues: 10, assumeNormalized: false))]); + var port = new FakeFacetPort().With("facets.brand", "acme", "globex"); + VocabularyCache cache = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, NullLogger.Instance, TestContext.Current.CancellationToken, + composesUnicode: () => true); + + Assert.Equal(["acme", "globex"], cache.Snapshot()["brand"].Originals); + } + + [Fact] + public async Task ApplyVocabularyAsync_WildcardFacetWithNoStar_LogsK48NamingTheFacet() + { + var configuration = Configuration( + [("brand", Vocabulary(maxValues: 10))], + wildcard: new KnowledgeWildcardConfiguration { Value = "*", Facets = ["brand"] }); + var port = new FakeFacetPort().With("facets.brand", "acme", "globex"); + VocabularyCache cache = new(); + RecordingLoggerFactory loggers = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, loggers.CreateLogger("test"), TestContext.Current.CancellationToken, + composesUnicode: () => true); + + var line = Assert.Single(loggers.Of(2)); + Assert.Equal("brand", line.Field("Facet")); + Assert.Contains(2, port.Reads.Where(r => r.Path == "facets.brand").Select(r => r.Limit)); + } + + [Fact] + public async Task ApplyVocabularyAsync_WildcardFacetWithStar_NoWarning() + { + var configuration = Configuration( + [("brand", Vocabulary(maxValues: 10))], + wildcard: new KnowledgeWildcardConfiguration { Value = "*", Facets = ["brand"] }); + + // The vocabulary read itself carries the wildcard (stripped by K6); the K48 read is a + // separate, small read that must see it. + var port = new FakeFacetPort().With("facets.brand", "acme", "globex", "*"); + VocabularyCache cache = new(); + RecordingLoggerFactory loggers = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, loggers.CreateLogger("test"), TestContext.Current.CancellationToken, + composesUnicode: () => true); + + Assert.Empty(loggers.Of(2)); + } + + [Fact] + public async Task ApplyVocabularyAsync_WildcardOnlyDocumentAndFacetAwarePortThrowsOnTheK48Read_WarnsAndBootSucceeds() + { + // K48 sits under "warned, not refused": a wildcard-only document (no vocabulary: slot + // anywhere) still reaches this read once its port is facet-aware (Task A4), and a store that + // cannot serve the small K48 sample -- for example, no keyword payload index at this path on + // Qdrant -- must not turn a document that was booting into one that cannot. + var configuration = Configuration( + wildcard: new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to"] }, + extraFromState: ["applies_to"]); + var port = new FakeFacetPort().ThrowsOn( + "facets.applies_to", new InvalidOperationException("no keyword payload index at this path")); + VocabularyCache cache = new(); + RecordingLoggerFactory loggers = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, loggers.CreateLogger("test"), TestContext.Current.CancellationToken); + + var line = Assert.Single(loggers.Of(3)); + Assert.Equal(LogLevel.Warning, line.Level); + Assert.Equal("applies_to", line.Field("Facet")); + Assert.Empty(cache.Snapshot()); + } + + [Fact] + public void ComposesUnicode_UnderThisTestHostsInvariantGlobalization_IsFalse() + { + // Nothing else pins this method itself: every other row drives the outcome through the + // composesUnicode override seam, so a regression that made ComposesUnicode() always report + // true (for example, swapping its escaped "Å" literal for typed characters, which + // reads identically but is pre-composed by the time the source file reaches disk) would pass + // every one of them. This project runs under InvariantGlobalization=true, where + // string.Normalize is a no-op, so the real method must report false here. + Assert.False(KnowledgeStartup.ComposesUnicode()); + } + + [Fact] + public async Task ApplyVocabularyAsync_NoVocabularyAndNoWildcardFacets_DoesNothing() + { + var configuration = Configuration(); + FakeFacetPort port = new(); + VocabularyCache cache = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, NullLogger.Instance, TestContext.Current.CancellationToken); + + Assert.Empty(port.Reads); + Assert.Empty(cache.Snapshot()); + } + + [Fact] + public async Task ApplyVocabularyAsync_HostBoundPortNotFacetAware_FailsNamingIFacetVocabularyPort() + { + // K27's first exit: options.UseKnowledgeRetrieval names a port of the host's own, and that + // port does not implement IFacetVocabularyPort. + var configuration = Configuration([("brand", Vocabulary(maxValues: 10))]); + HostBoundPort knowledge = new(); + VocabularyCache cache = new(); + + var failure = await Assert.ThrowsAsync( + () => KnowledgeStartup.ApplyVocabularyAsync( + configuration, knowledge, cache, NullLogger.Instance, TestContext.Current.CancellationToken).AsTask()); + + Assert.Contains(nameof(IFacetVocabularyPort), failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task ApplyVocabularyAsync_CompositeBuiltPortNotFacetAware_FailsNamingIFacetVocabularyPort() + { + // K27's second exit: CompositeKnowledgeStoreFactory matched providers.knowledge.kind to an + // adapter whose port also does not implement IFacetVocabularyPort. + var configuration = Configuration([("brand", Vocabulary(maxValues: 10))]); + CompositeBuiltPort knowledge = new(); + VocabularyCache cache = new(); + + var failure = await Assert.ThrowsAsync( + () => KnowledgeStartup.ApplyVocabularyAsync( + configuration, knowledge, cache, NullLogger.Instance, TestContext.Current.CancellationToken).AsTask()); + + Assert.Contains(nameof(IFacetVocabularyPort), failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task ApplyVocabularyAsync_NoPortAtAll_FailsNamingIFacetVocabularyPort() + { + // K27's third exit: no adapter was registered, so KnowledgeStartup.OpenAsync returns null. + var configuration = Configuration([("brand", Vocabulary(maxValues: 10))]); + VocabularyCache cache = new(); + + var failure = await Assert.ThrowsAsync( + () => KnowledgeStartup.ApplyVocabularyAsync( + configuration, knowledge: null, cache, NullLogger.Instance, TestContext.Current.CancellationToken).AsTask()); + + Assert.Contains(nameof(IFacetVocabularyPort), failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task ApplyVocabularyAsync_WildcardOnlyDocumentAndPortNotFacetAware_SkipsSilently() + { + // A pre-existing wildcard-plan document (no vocabulary: slot anywhere) must not suddenly + // require IFacetVocabularyPort just because it uses wildcard.facets -- K27's refusal is + // scoped to a document that declares vocabulary:. + var configuration = Configuration( + wildcard: new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to"] }, + extraFromState: ["applies_to"]); + HostBoundPort knowledge = new(); + VocabularyCache cache = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, knowledge, cache, NullLogger.Instance, TestContext.Current.CancellationToken); + + Assert.Empty(cache.Snapshot()); + } + + private static SlotVocabularyConfiguration Vocabulary(int maxValues, bool assumeNormalized = false) + => new() { From = "knowledge", MaxValues = maxValues, AssumeNormalized = assumeNormalized }; + + private static AgentCoreConfiguration Configuration( + (string Slot, SlotVocabularyConfiguration Vocabulary)[]? vocabularySlots = null, + KnowledgeWildcardConfiguration? wildcard = null, + IReadOnlyList? extraFromState = null) + { + vocabularySlots ??= []; + extraFromState ??= []; + + Dictionary state = new(StringComparer.Ordinal); + foreach (var (slot, vocabulary) in vocabularySlots) + { + state[slot] = new StateSlotConfiguration + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + Vocabulary = vocabulary, + }; + } + + foreach (var slot in extraFromState) + { + state.TryAdd(slot, new StateSlotConfiguration { Type = StateSlotType.String, Writer = StateWriter.Extractor }); + } + + List fromState = [.. vocabularySlots.Select(entry => entry.Slot), .. extraFromState]; + + return new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Name = "vocabulary-startup", + State = state, + Providers = new ProvidersConfiguration + { + Knowledge = new KnowledgeProviderConfiguration + { + Kind = "test", + Collection = "kb", + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + Scope = new KnowledgeScopeConfiguration + { + Template = "facets.{key}", + FromState = fromState, + Wildcard = wildcard, + }, + }, + }, + }; + } + + /// A live port that records every read, and answers a canned map by path. + private sealed class FakeFacetPort : IKnowledgeRetrievalPort, IFacetVocabularyPort + { + private readonly Dictionary> _byPath = new(StringComparer.Ordinal); + private readonly Dictionary _throwsByPath = new(StringComparer.Ordinal); + + public List<(string Path, int Limit)> Reads { get; } = []; + + public FakeFacetPort With(string path, params string[] values) + { + _byPath[path] = values; + return this; + } + + public FakeFacetPort ThrowsOn(string path, Exception exception) + { + _throwsByPath[path] = exception; + return this; + } + + public ValueTask> ReadAsync( + string path, int limit, CancellationToken cancellationToken = default) + { + Reads.Add((path, limit)); + + if (_throwsByPath.TryGetValue(path, out var exception)) + { + throw exception; + } + + return ValueTask.FromResult(_byPath.TryGetValue(path, out var values) ? values : (IReadOnlyList)[]); + } + + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + } + + /// Stands in for a port options.UseKnowledgeRetrieval named, with no facet read. + private sealed class HostBoundPort : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + } + + /// Stands in for a port CompositeKnowledgeStoreFactory built, with no facet read. + private sealed class CompositeBuiltPort : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + } +} + +/// +/// The rest of task A7's wiring, exercised through itself: the +/// configuration warnings logged below telemetry, ValidateLinkerNames run after the linker +/// registry is built, the vocabulary read reaching a real adapter-built port, and the background +/// refresh started. +/// +public sealed class AgentCoreBootVocabularyTests +{ + [Fact] + public async Task BootAsync_ASingleFacetAmbiguityDocument_LogsTheConfigurationWarningBelowTelemetry() + { + // R1's actual plumbing: a warning EvaluateStructure raised (K33 here) must reach the log, + // through ConfigurationStartup.Load's returned Warnings and AgentCoreBoot's own logger. + RecordingLoggerFactory loggers = new(); + FacetKnowledgeAdapter adapter = new(); + adapter.Port.With("facets.machine", "ct900", "ct1200"); + + await using var boot = Boot(Document(Vocabulary(10)), adapter, 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(); + + Assert.Contains(warnings, line => line.Message.Contains("at most one", StringComparison.Ordinal)); + } + + [Fact] + public void Load_AGraphDocumentWithAmbiguity_ReturnsTheK39Warning() + { + // K39: channel 1 cannot fire on a graph: document, so ambiguity: there is a boot warning + // (CheckVocabularyAndAmbiguity, task A1) that ConfigurationStartup.Load must not discard. + var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; + StateSlotConfiguration facet = new() { Type = StateSlotType.String, Writer = StateWriter.Extractor, EnumValues = [] }; + + var configuration = new AgentCoreConfiguration + { + ApiVersion = "agentcore/v1", + Name = "graph-ambiguity", + Graph = new GraphConfiguration(), + Extractor = new ExtractorConfiguration { Model = new ModelReference { Ref = "small" } }, + State = new Dictionary(StringComparer.Ordinal) + { + ["applies_to"] = facet with { EnumValues = [JsonValue.Create("a")!] }, + ["brand"] = facet with { EnumValues = [JsonValue.Create("b")!] }, + }, + Providers = new ProvidersConfiguration + { + Llm = [new LlmProviderConfiguration { Kind = "openai", Model = "gpt", As = "small" }], + Knowledge = new KnowledgeProviderConfiguration + { + Kind = "qdrant", + Collection = "kb", + Fields = new KnowledgeFieldsConfiguration { Body = "text" }, + Scope = new KnowledgeScopeConfiguration + { + Template = "facets.{key}", + FromState = ["applies_to", "brand"], + Wildcard = wildcard, + }, + Ambiguity = new KnowledgeAmbiguityConfiguration(), + }, + }, + }; + + AgentCoreOptions options = new() { Configuration = configuration }; + + var result = ConfigurationStartup.Load(options); + + var warning = Assert.Single(result.Warnings); + Assert.Equal("/providers/knowledge/ambiguity", warning.Pointer); + } + + [Fact] + public async Task BootAsync_AZeroValueVocabularyRead_FailsBootNamingTheSlot() + { + FacetKnowledgeAdapter adapter = new(); + + // No .With(...) call: the fake answers every path with an empty list. + await using var boot = Boot(Document(Vocabulary(10)), adapter); + + var failure = await Assert.ThrowsAsync( + () => boot.BootAsync(TestContext.Current.CancellationToken).AsTask()); + + Assert.Contains("machine", failure.Message, StringComparison.Ordinal); + Assert.True(adapter.Port.Reads.Count > 0); + } + + [Fact] + public async Task BootAsync_ABadLinkerName_FailsBootBeforeReadingTheVocabulary() + { + FacetKnowledgeAdapter adapter = new(); + adapter.Port.With("facets.machine", "ct900", "ct1200"); + + await using var boot = Boot(Document(Vocabulary(10, linker: "bogus")), adapter); + + var failure = await Assert.ThrowsAsync( + () => boot.BootAsync(TestContext.Current.CancellationToken).AsTask()); + + Assert.Contains("bogus", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task BootAsync_AHostRegisteredLinkerName_Succeeds() + { + FacetKnowledgeAdapter adapter = new(); + adapter.Port.With("facets.machine", "ct900", "ct1200"); + + await using var boot = Boot( + Document(Vocabulary(10, linker: "custom")), adapter, linkers: [new NamedLinker("custom")]); + + await boot.BootAsync(TestContext.Current.CancellationToken); + + Assert.NotNull(boot.Sessions); + } + + [Fact] + public async Task BootAsync_AHostRegisteredLinkerName_ItsResultReachesTheExtractedState() + { + // "Boot succeeds" (the fact above) would have passed against the exact bug this fact exists + // to catch: CallSessionFactory hard-coded an empty linker registry, so a host's own linker + // validated by name at boot and was then never actually consulted. Only running a real turn + // and reading back what the CUSTOM linker -- not exact, not nothing -- wrote proves the + // registry travelled all the way from UseStateValueLinkers into the extractor. + FacetKnowledgeAdapter adapter = new(); + adapter.Port.With("facets.machine", "ct900", "ct1200"); + + var configuration = Document(Vocabulary(10, linker: "custom")); + + AgentCoreOptions options = new() { Configuration = configuration }; + options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("okay, noted")) + .Route("fill", new FragmentingChatClient("""{"machine":"ct900"}"""))); + options.UseKnowledgeStores(adapter); + options.UseStateValueLinkers(new FixedResultLinker("custom", "ct1200")); + + await using var boot = new AgentCoreBoot(Options.Create(options), NullLoggerFactory.Instance); + await boot.BootAsync(TestContext.Current.CancellationToken); + + var session = boot.Sessions.Create(); + await session.RunTurnAsync("what machine do I have", TestContext.Current.CancellationToken); + + // exact would resolve the mention "ct900" to "ct900" itself; the custom linker ignores the + // mention and always answers "ct1200" -- chosen so the two are never accidentally the same. + Assert.Equal("ct1200", session.State.Read("machine")?.GetValue()); + } + + [Fact] + public async Task BootAsync_ValidVocabularyDocument_BuildsAWorkingSessionFactory() + { + FacetKnowledgeAdapter adapter = new(); + adapter.Port.With("facets.machine", "ct900", "ct1200"); + + await using var boot = Boot(Document(Vocabulary(10)), adapter); + await boot.BootAsync(TestContext.Current.CancellationToken); + + var session = boot.Sessions.Create(); + Assert.NotNull(session); + } + + [Fact] + public async Task BootAsync_ARefreshIntervalConfigured_StartsTheBackgroundRefresh() + { + FacetKnowledgeAdapter adapter = new(); + adapter.Port.With("facets.machine", "ct900", "ct1200"); + FakeTimeProvider time = new(DateTimeOffset.UnixEpoch); + + await using var boot = Boot(Document(Vocabulary(10, refreshSeconds: 60)), adapter, timeProvider: time); + await boot.BootAsync(TestContext.Current.CancellationToken); + + var readsAtBoot = adapter.Port.Reads.Count; + Assert.True(readsAtBoot > 0); + + for (var attempt = 0; attempt < 200 && adapter.Port.Reads.Count <= readsAtBoot; attempt++) + { + time.Advance(TimeSpan.FromSeconds(60)); + await Task.Delay(10, TestContext.Current.CancellationToken); + } + + Assert.True(adapter.Port.Reads.Count > readsAtBoot); + } + + private static SlotVocabularyConfiguration Vocabulary(int maxValues, string? linker = null, int refreshSeconds = 0) + => new() + { + From = "knowledge", + MaxValues = maxValues, + Linker = linker ?? SlotVocabularyConfiguration.DefaultLinker, + RefreshSeconds = refreshSeconds, + + // K44 is covered at the ApplyVocabularyAsync unit level (composesUnicode seam). These + // boot-level facts are about other wiring, and the AspNetCore test host really does run + // under InvariantGlobalization=true, so without this every one of them would hit K44's + // refusal first. + AssumeNormalized = true, + }; + + private static AgentCoreConfiguration Document(SlotVocabularyConfiguration vocabulary) + => new() + { + ApiVersion = "agentcore/v1", + Name = "vocabulary-boot", + Extractor = new ExtractorConfiguration { Model = new ModelReference { Ref = "fill" } }, + State = new Dictionary(StringComparer.Ordinal) + { + ["machine"] = new StateSlotConfiguration + { + Type = StateSlotType.String, + Writer = StateWriter.Extractor, + Vocabulary = vocabulary, + }, + }, + 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 + { + Template = "facets.{key}", + FromState = ["machine"], + Wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["machine"] }, + }, + Ambiguity = new KnowledgeAmbiguityConfiguration(), + }, + }, + Policy = new PolicyConfiguration + { + Initial = "answering", + Stages = [new StageConfiguration { Id = "answering", Agent = "resolver", Terminal = true }], + }, + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration + { + Id = "resolver", + Instructions = "I answer about one machine", + Knowledge = new AgentKnowledgeConfiguration { Mode = KnowledgeMode.Prefetch, Scoped = true }, + }, + ], + }, + }; + + private static AgentCoreBoot Boot( + AgentCoreConfiguration configuration, + FacetKnowledgeAdapter adapter, + RecordingLoggerFactory? loggers = null, + TimeProvider? timeProvider = null, + IStateValueLinker[]? linkers = null) + { + AgentCoreOptions options = new() + { + Configuration = configuration, + LoggerFactory = loggers, + TimeProvider = timeProvider, + }; + + options.UseChatClients(_ => new RoutingChatClientFactory(new FragmentingChatClient("hello"))); + options.UseKnowledgeStores(adapter); + + if (linkers is { Length: > 0 }) + { + options.UseStateValueLinkers(linkers); + } + + return new AgentCoreBoot(Options.Create(options), (ILoggerFactory?)loggers ?? NullLoggerFactory.Instance); + } + + /// Answers providers.knowledge.kind: test with a live facet-aware port. + private sealed class FacetKnowledgeAdapter : IKnowledgeStoreAdapter + { + public string Kind => "test"; + + public bool CanServeSearch => true; + + public bool CanScope => true; + + public FacetKnowledgePort Port { get; } = new(); + + public ValueTask CreateSearchAsync( + KnowledgeProviderConfiguration entry, + ISecretResolverPort? secrets, + IEmbeddingGenerator>? embeddings, + bool requireScope, + CancellationToken cancellationToken = default) + => ValueTask.FromResult(Port); + } + + /// A live port that records every read, and answers a canned map by path. + private sealed class FacetKnowledgePort : IKnowledgeRetrievalPort, IFacetVocabularyPort + { + private readonly Dictionary> _byPath = new(StringComparer.Ordinal); + + public List<(string Path, int Limit)> Reads { get; } = []; + + public FacetKnowledgePort With(string path, params string[] values) + { + _byPath[path] = values; + return this; + } + + public ValueTask> ReadAsync( + string path, int limit, CancellationToken cancellationToken = default) + { + lock (Reads) + { + Reads.Add((path, limit)); + } + + return ValueTask.FromResult(_byPath.TryGetValue(path, out var values) ? values : (IReadOnlyList)[]); + } + + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + } + + /// A linker that never links, registered under a host-chosen name. + private sealed class NamedLinker(string name) : IStateValueLinker + { + public string Name { get; } = name; + + public LinkResult Link(string mention, VocabularyView vocabulary, IReadOnlySet lastNamed) + => new(LinkOutcome.NoMatch, []); + } + + /// + /// Always links to the same value, ignoring the mention. Distinguishable on purpose: no reading + /// of this test can mistake its output for exact's. + /// + private sealed class FixedResultLinker(string name, string result) : IStateValueLinker + { + public string Name { get; } = name; + + public LinkResult Link(string mention, VocabularyView vocabulary, IReadOnlySet lastNamed) + => new(LinkOutcome.Linked, [result]); + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/Sessions/VocabularyRefreshServiceTests.cs b/tests/AgentCore.AspNetCore.Tests/Sessions/VocabularyRefreshServiceTests.cs new file mode 100644 index 00000000..8743e820 --- /dev/null +++ b/tests/AgentCore.AspNetCore.Tests/Sessions/VocabularyRefreshServiceTests.cs @@ -0,0 +1,136 @@ +using AgentCore.Application.Ports; +using AgentCore.Application.State; +using AgentCore.AspNetCore.Sessions; +using AgentCore.TestSupport; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging.Abstractions; +using Xunit; + +namespace AgentCore.AspNetCore.Tests.Sessions; + +/// +/// Section 11's refresh rows: a failed or degenerate refresh keeps the cache's last good view and +/// logs, and the loop itself follows CallSessionSweeper's idiom. +/// +public sealed class VocabularyRefreshServiceTests +{ + [Fact] + public async Task RefreshAsync_TheReadThrows_KeepsTheLastGoodViewAndLogs() + { + VocabularyCache cache = new(); + cache.Replace("brand", ["acme", "globex"], maxValues: 10); + var before = cache.Snapshot()["brand"]; + + RecordingLoggerFactory loggers = new(); + FailingPort port = new(new InvalidOperationException("qdrant is down")); + + VocabularyRefreshService service = new( + "brand", "facets.brand", 10, null, 900, port, cache, + TimeProvider.System, loggers.CreateLogger()); + + await service.RefreshAsync(TestContext.Current.CancellationToken); + + Assert.Same(before, cache.Snapshot()["brand"]); + var line = Assert.Single(loggers.Of(1)); + Assert.Equal("brand", line.Field("Slot")); + Assert.Same(port.Failure, line.Exception); + } + + [Fact] + public async Task RefreshAsync_TheReadReturnsExactlyMaxValues_KeepsTheLastGoodViewAndLogsDegenerate() + { + // K46: a successful but truncated read must not overwrite the last good view. + VocabularyCache cache = new(); + cache.Replace("brand", ["acme", "globex"], maxValues: 10); + var before = cache.Snapshot()["brand"]; + + RecordingLoggerFactory loggers = new(); + FakePort port = new(["a", "b", "c"]); + + VocabularyRefreshService service = new( + "brand", "facets.brand", 3, null, 900, port, cache, + TimeProvider.System, loggers.CreateLogger()); + + await service.RefreshAsync(TestContext.Current.CancellationToken); + + Assert.Same(before, cache.Snapshot()["brand"]); + var line = Assert.Single(loggers.Of(2)); + Assert.Equal("brand", line.Field("Slot")); + Assert.IsType(line.Exception); + } + + [Fact] + public async Task RefreshAsync_TheReadReturnsAGoodSet_ReplacesTheView() + { + VocabularyCache cache = new(); + cache.Replace("brand", ["acme"], maxValues: 10); + + FakePort port = new(["acme", "globex"]); + VocabularyRefreshService service = new( + "brand", "facets.brand", 10, null, 900, port, cache, + TimeProvider.System, NullLogger.Instance); + + await service.RefreshAsync(TestContext.Current.CancellationToken); + + Assert.Equal(["acme", "globex"], cache.Snapshot()["brand"].Originals); + } + + [Fact] + public async Task ExecuteAsync_TheTimerTicks_RunsARefreshOnTheConfiguredInterval() + { + VocabularyCache cache = new(); + cache.Replace("brand", ["acme"], maxValues: 10); + + FakePort port = new(["acme", "globex"]); + FakeTimeProvider time = new(DateTimeOffset.UnixEpoch); + + VocabularyRefreshService service = new( + "brand", "facets.brand", 10, null, refreshSeconds: 60, port, cache, + time, NullLogger.Instance); + + await service.StartAsync(TestContext.Current.CancellationToken); + + // BackgroundService.StartAsync runs ExecuteAsync through Task.Run, so the PeriodicTimer may + // not exist yet when this returns. Retry the advance until the fake port reports the tick + // landed, rather than assuming a single Advance lands on a timer that is not armed yet. + for (var attempt = 0; attempt < 200 && !port.Read.Task.IsCompleted; attempt++) + { + time.Advance(TimeSpan.FromSeconds(60)); + await Task.Delay(10, TestContext.Current.CancellationToken); + } + + await port.Read.Task.WaitAsync(TimeSpan.FromSeconds(1), TestContext.Current.CancellationToken); + + // The cache write is asynchronous from the read that unblocked Read.Task above, so give the + // continuation a chance to run before reading the cache back. + for (var attempt = 0; attempt < 100 && cache.Snapshot()["brand"].Originals.Count != 2; attempt++) + { + await Task.Delay(10, TestContext.Current.CancellationToken); + } + + Assert.Equal(["acme", "globex"], cache.Snapshot()["brand"].Originals); + + await service.StopAsync(TestContext.Current.CancellationToken); + } + + private sealed class FakePort(IReadOnlyList values) : IFacetVocabularyPort + { + public TaskCompletionSource Read { get; } = new(); + + public ValueTask> ReadAsync( + string path, int limit, CancellationToken cancellationToken = default) + { + Read.TrySetResult(); + return ValueTask.FromResult(values); + } + } + + private sealed class FailingPort(Exception failure) : IFacetVocabularyPort + { + public Exception Failure { get; } = failure; + + public ValueTask> ReadAsync( + string path, int limit, CancellationToken cancellationToken = default) + => throw Failure; + } +} diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/AmbiguityIntegrationTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/AmbiguityIntegrationTests.cs new file mode 100644 index 00000000..ffcdccaf --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/AmbiguityIntegrationTests.cs @@ -0,0 +1,878 @@ +using System.Reflection; +using System.Runtime.CompilerServices; +using AgentCore.Application.Calls; +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.State; +using AgentCore.Domain.Knowledge; +using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; +using AgentCore.Infrastructure.Tests.Fakes; +using AgentCore.TestSupport; +using Grpc.Core; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +using Qdrant.Client; +using Qdrant.Client.Grpc; +using Xunit; + +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; + +/// +/// Section 12's "Vocabulary and probe -- against real Qdrant" list, and the Task A7 debt: a live +/// turn proving the boot-filled reaches the +/// extractor's gate, not just a hand-seeded one. +/// +/// +/// +/// , 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, instead of letting the framework's tool-calling loop run, +/// reaches directly into the compiled agent's own TextSearchProvider and calls its private search +/// delegate itself -- the same delegate KnowledgeProviderFactory.Create built from the real store, +/// reached by reflection into a third-party field exactly as +/// AgentCore.Application.Tests.Knowledge.KnowledgeProbeTests already does, which needs no grant +/// because reflection does not go through the C# compiler's accessibility check. Calling it from inside +/// the fake model, rather than after the turn, is what keeps TurnAmbients.Current populated: that +/// ambient is only entered around CallSession's own 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, +/// the same way 's wildcard fact does. +/// +/// +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"; + + /// 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 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 QdrantClient Client { get; private set; } = null!; + + public async ValueTask InitializeAsync() + { + if (!QdrantServer.IsConfigured) + { + return; + } + + Client = QdrantServer.CreateClient(); + + // The 30-card synthetic corpus, unmodified, plus the multi-machine card the brief calls 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); + + var added = new[] + { + CardWithModelList(MultiMachineCardId, $"err {MultiMachineToken} shared drive belt code on the console", MultiMachineModels), + }; + await Client.UpsertAsync(Name, added, cancellationToken: TestContext.Current.CancellationToken); + + // One call 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); + } + + public async ValueTask DisposeAsync() + { + if (Client is null) + { + return; + } + + try + { + await Client.DeleteCollectionAsync(Name); + } + finally + { + Client.Dispose(); + } + } + + 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 + { + 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 + { + 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 + { + StructValue = new Struct + { + Fields = + { + ["model"] = modelValue, + ["audience"] = new Value { StringValue = Audience }, + }, + }, + }; + point.Payload["source"] = new Value + { + StructValue = new Struct + { + Fields = + { + ["ref"] = new Value { StringValue = $"manifest-{cardId}" }, + ["locator"] = new Value { StringValue = "p.1" }, + }, + }, + }; + + return point; + } +} + +[Collection(QdrantServerCollection.Name)] +public sealed class AmbiguityIntegrationTests : IClassFixture +{ + private const string ModelDescription = "The model, as printed on the machine."; + + 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 = + """ + apiVersion: agentcore/v1 + name: ambiguity-probe-integration + state: + model: + type: string + writer: extractor + description: "The model, as printed on the machine." + vocabulary: { from: knowledge } + audience: + type: string + writer: const + value: everyone + enum: [everyone] + extractor: + model: { ref: fill } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [model, audience] + wildcard: { value: "*", facets: [model] } + ambiguity: { maxCandidates: {{maxCandidates}}, maxAsks: 2 } + agents: + items: + - id: only + knowledge: { mode: tool, scoped: true } + """; + + /// One droppable-shaped facet only: dropping it would open the scope empty (K33). + private const string SingleFacetYaml = + """ + apiVersion: agentcore/v1 + name: ambiguity-probe-single-facet + state: + model: + type: string + writer: extractor + vocabulary: { from: knowledge } + extractor: + model: { ref: fill } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + fromState: [model] + wildcard: { value: "*", facets: [model] } + ambiguity: {} + agents: + items: + - id: only + knowledge: { mode: tool, scoped: true } + """; + + /// No scope: at all: the agent opens the whole corpus regardless of what the caller has said. + private const string UnscopedYaml = + """ + apiVersion: agentcore/v1 + name: ambiguity-probe-unscoped + agents: + items: + - { id: only, instructions: "answer the caller", knowledge: { mode: tool, scoped: false } } + """; + + /// No ambiguity, no wildcard: a plain vocabulary: slot the extractor writes and the gate checks. + private const string VocabularyOnlyYaml = + """ + apiVersion: agentcore/v1 + name: vocabulary-cache-reaches-extractor + state: + model: + type: string + writer: extractor + description: "The model, as printed on the machine." + vocabulary: { from: knowledge } + extractor: + model: { ref: fill } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + fields: { body: text } + scope: + template: "facets.{key}" + agents: + items: + - id: only + instructions: "answer the caller" + """; + + private readonly AmbiguityCorpusFixture _corpus; + + public AmbiguityIntegrationTests(AmbiguityCorpusFixture corpus) => _corpus = corpus; + + // ----------------------------------------------------------------------------------------- + // Section 12's twelve real-Qdrant rows. + // ----------------------------------------------------------------------------------------- + + /// 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}"; + + try + { + 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); + + // 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); + } + } + + /// 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); + + 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); + } + + /// 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}"; + + try + { + 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); + + var client = await RunAsync(BuildTwoFacetYaml(), KbShapedCorpus.PlainQuery, store); + + var 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); + } + } + + /// 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); + + var text = Assert.Single(client.Results).Text; + foreach (var model in AmbiguityCorpusFixture.MultiMachineModels) + { + Assert.Contains(model, text, StringComparison.Ordinal); + } + } + + /// More than maxCandidates names none of them. + [QdrantFact] + public async Task MoreThanMaxCandidates_NamesNone() + { + var client = await RunAsync(BuildTwoFacetYaml(maxCandidates: 2), KbShapedCorpus.PlainQuery); + + 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); + } + + /// + /// A probe spread publishes no sources. TurnSources is internal to CallSession 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); + + // 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)); + } + + /// 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)); + } + + /// A facet read against a collection with maxValues values fails startup. + [QdrantFact] + public async Task FacetRead_AgainstACollectionWithMaxValuesValues_FailsStartup() + { + // This is the exact call sequence KnowledgeStartup.ApplyVocabularyAsync runs for one slot + // (port.ReadAsync then VocabularyCache.Replace with the same limit) -- KnowledgeStartup itself + // is internal to AgentCore.AspNetCore, a project this one does not reference. + var port = BuildStore(); + var values = await port.ReadAsync("facets.model", limit: 3, TestContext.Current.CancellationToken); + + Assert.Equal(3, values.Count); + + var vocabulary = new VocabularyCache(); + var failure = Assert.Throws(() => vocabulary.Replace("model", values, maxValues: 3)); + Assert.Equal("model", failure.Slot); + } + + /// A facet read against a path with no keyword index fails startup. + [QdrantFact] + public async Task FacetRead_AgainstAPathWithNoKeywordIndex_FailsStartup() + { + var port = BuildStore(); + + // "body" carries no payload index at all in this corpus -- the same uncaught exception + // ApplyVocabularyAsync would let propagate straight out of a boot it never wraps in a try. + var failure = await Assert.ThrowsAsync( + async () => await port.ReadAsync("body", 100, TestContext.Current.CancellationToken)); + + Assert.Equal(StatusCode.InvalidArgument, failure.StatusCode); + // §10 requires the exception to name the offending path -- the only part of this row a real + // Qdrant response actually decides, as opposed to the fact of throwing at all. + Assert.Contains("body", failure.Message, StringComparison.Ordinal); + } + + /// 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.Contains("holds nothing", Assert.Single(client.Results).Text, StringComparison.Ordinal); + } + + /// 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}"; + + try + { + var store = await FillAdHocCollectionAsync(collection, [], scoped: false); + + var client = await RunAsync(UnscopedYaml, "anything at all", store); + + Assert.Empty(client.Results); + } + finally + { + await _corpus.Client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + } + } + + /// + /// 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); + + var client = await RunAsync( + BuildTwoFacetYaml(), $"the screen says {AmbiguityCorpusFixture.MultiMachineToken}", port, loggers); + + Assert.Contains("holds nothing", Assert.Single(client.Results).Text, StringComparison.Ordinal); + + // EventId 17: KnowledgeProbeFailed -- the probe's own failure event. + var probeFailed = Assert.Single(loggers.Of(17)); + Assert.Equal("model", probeFailed.Field("Facet")); + + // 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)); + } + + // ----------------------------------------------------------------------------------------- + // The Task A7 debt: a live turn proving the boot-filled vocabulary cache reaches the extractor. + // ----------------------------------------------------------------------------------------- + + /// + /// A value read live from the real collection's own facet -- never hand-seeded -- reaches the + /// extractor's gate and links. Task A7 proved the cache reaches CallSessionFactory only by + /// code review, a construction smoke test and a shared-instance proof in the refresh test; this is + /// the first place a value that could only have come from that boot read is actually linked. + /// + [QdrantFact] + public async Task LiveTurn_BootFilledVocabularyCache_LinksAReallyReadValue() + { + var vocabulary = await SeedVocabularyFromRealQdrantAsync(); + + RoutingChatClientFactory chatClients = new(new FixedTextChatClient("okay.")); + chatClients.Route("fill", new FixedTextChatClient("""{"model":"ct900ent"}""")); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(VocabularyOnlyYaml), + new AgentCompilationContext(chatClients) { Knowledge = BuildStore() }); + + var extractor = CallSessionFactory.CreateExtractor(compiled, chatClients); + var session = new CallSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), extractor, vocabulary: vocabulary) + .Create("call-a7-live-extractor-positive"); + + await session.RunTurnAsync("I have a CT900ENT", TestContext.Current.CancellationToken); + + // "ct900ent" is not a value this test wrote anywhere -- it is the corpus's own spelling, read + // back from Qdrant into `vocabulary` a few lines above and nowhere else in this method. + Assert.Equal("ct900ent", session.State.Read("model")?.GetValue()); + } + + /// + /// The gate's other half: a value the same real read never produced is refused, proving the accept + /// above is really checking the boot-filled cache and not simply accepting any string. + /// + [QdrantFact] + public async Task LiveTurn_AValueTheBootReadNeverProduced_IsRefused() + { + var vocabulary = await SeedVocabularyFromRealQdrantAsync(); + + RoutingChatClientFactory chatClients = new(new FixedTextChatClient("okay.")); + chatClients.Route("fill", new FixedTextChatClient("""{"model":"xt385"}""")); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(VocabularyOnlyYaml), + new AgentCompilationContext(chatClients) { Knowledge = BuildStore() }); + + var extractor = CallSessionFactory.CreateExtractor(compiled, chatClients); + var session = new CallSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), extractor, vocabulary: vocabulary) + .Create("call-a7-live-extractor-negative"); + + await session.RunTurnAsync("I have an XT385", TestContext.Current.CancellationToken); + + Assert.Null(session.State.Read("model")); + } + + // ----------------------------------------------------------------------------------------- + // Helpers. + // ----------------------------------------------------------------------------------------- + + private async Task SeedVocabularyFromRealQdrantAsync() + { + var port = BuildStore(); + var values = await port.ReadAsync("facets.model", limit: 2000, TestContext.Current.CancellationToken); + + var vocabulary = new VocabularyCache(); + vocabulary.Replace("model", values, maxValues: 2000, wildcardValue: "*"); + return vocabulary; + } + + 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("{}")); + + var compiled = ConfigurationCompiler.Compile( + ConfigurationLoader.LoadYaml(yaml), + new AgentCompilationContext(chatClients) + { + Knowledge = port ?? BuildStore(limit), + Loggers = loggers, + }); + + capture.Bind(SearchProviderOf(compiled.Agents["only"])); + + var extractor = CallSessionFactory.CreateExtractor(compiled, chatClients); + var session = new CallSessionFactory( + compiled, new GuardEvaluator(compiled.Configuration.Guards), extractor, vocabulary: new VocabularyCache()) + .Create($"call-{Guid.NewGuid():N}"); + + await session.RunTurnAsync(callerQuestion, TestContext.Current.CancellationToken); + + return capture; + } + + private static string BuildTwoFacetYaml(int maxCandidates = 6) + => TwoFacetYaml.Replace("{{maxCandidates}}", maxCandidates.ToString(), StringComparison.Ordinal); + + private QdrantKnowledgeStore BuildStore(int limit = 10) => BuildStoreOver(_corpus.Name, limit, scoped: true); + + private QdrantKnowledgeStore BuildStoreOver(string collection, int limit, bool scoped) => new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Collection = collection, + Scoped = scoped, + VectorName = "dense", + Fields = KbShapedCorpus.Fields, + ScopeTemplate = KbShapedCorpus.ScopeTemplate, + ScopeWildcard = "*", + ScopeWildcardFacets = ["model"], + Analyzer = KbShapedCorpus.Analyzer, + Limit = limit, + ScoreFloor = 0.0, + }); + + /// + /// 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 call already created on the server would be orphaned with nothing + /// left to drop it. Matches 's + /// own shape: creation, indexing and upsert all inside one try, one unconditional + /// DeleteCollectionAsync in the caller's own finally. + /// + private async Task FillAdHocCollectionAsync( + string collection, PointStruct[] points, bool scoped) + { + var cancellationToken = TestContext.Current.CancellationToken; + + await _corpus.Client.CreateCollectionAsync( + collection, + vectorsConfig: new VectorParamsMap + { + 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 BuildStoreOver(collection, limit: 10, scoped); + } + + private static TextSearchProvider SearchProviderOf(AIAgent agent) + { + var inner = agent.GetService() + ?? throw new InvalidOperationException("the compiled agent carries no ChatClientAgent."); + + return inner.AIContextProviders?.OfType().SingleOrDefault() + ?? throw new InvalidOperationException("the compiled agent carries no TextSearchProvider."); + } + + /// + /// 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) + { + _inner = inner; + _fullFacetCount = fullFacetCount; + } + + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + { + if (KnowledgeScopeScope.Current?.Facets.Count == _fullFacetCount) + { + return _inner.SearchAsync(query, cancellationToken); + } + + throw new InvalidOperationException("the probe's own second search is down (synthetic, for this row only)."); + } + } + + /// + /// Stands in for the turn's reply model. Rather than let the framework's own tool-calling loop + /// run, it reaches directly into the compiled agent's TextSearchProvider and calls its + /// private search delegate itself, from inside the same ambient scope + /// already opened around this call -- so TurnAmbients.Current is exactly what a real tool + /// invocation would see. + /// + private sealed class SearchCapturingChatClient : IChatClient + { + private readonly string _query; + + private Func>>? _search; + + internal SearchCapturingChatClient(string query) => _query = query; + + internal IReadOnlyList Results { get; private set; } = []; + + internal void Bind(TextSearchProvider provider) + => _search = TextSearchProviderInternals.SearchDelegate(provider); + + public async IAsyncEnumerable GetStreamingResponseAsync( + IEnumerable messages, + ChatOptions? options = null, + [EnumeratorCancellation] CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(messages); + + if (_search is { } search) + { + Results = [.. await search(_query, cancellationToken).ConfigureAwait(false)]; + } + + await Task.Yield(); + + var responseId = Guid.NewGuid().ToString("N"); + yield return new ChatResponseUpdate(ChatRole.Assistant, "noted.") + { + 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. + } + } + + /// + /// 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; + + 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"); + yield return new ChatResponseUpdate(ChatRole.Assistant, _text) + { + 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. + } + } +} diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetVocabularyTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetVocabularyTests.cs new file mode 100644 index 00000000..f5ef78a5 --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetVocabularyTests.cs @@ -0,0 +1,173 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Ports; +using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; +using AgentCore.Infrastructure.Tests.Fakes; +using Grpc.Core; +using Qdrant.Client; +using Qdrant.Client.Grpc; +using Xunit; + +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; + +/// +/// The 30-card synthetic corpus, built once for the class. Every test here only reads. +/// +public sealed class FacetVocabularyCorpusFixture : IAsyncLifetime +{ + public string Name { get; } = $"facet-vocab-{Guid.NewGuid():N}"; + + public QdrantClient Client { get; private set; } = null!; + + public async ValueTask InitializeAsync() + { + if (!QdrantServer.IsConfigured) + { + return; + } + + 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(); + } + } +} + +/// +/// against a real Qdrant: what §12's four acceptance +/// clauses ask of . +/// +[Collection(QdrantServerCollection.Name)] +public sealed class FacetVocabularyTests : IClassFixture +{ + private readonly FacetVocabularyCorpusFixture _corpus; + + public FacetVocabularyTests(FacetVocabularyCorpusFixture corpus) => _corpus = corpus; + + [QdrantFact] + public async Task ReadAsync_ReturnsEveryDistinctValueAtThePath() + { + var values = await Port().ReadAsync("facets.model", 100, TestContext.Current.CancellationToken); + + Assert.Equal(["ct900", "ct900ent", "ctsbs900"], values.Order(StringComparer.Ordinal)); + } + + [QdrantFact] + public async Task ReadAsync_ResultCountEqualsLimit_ReturnsExactlyLimitValues() + { + // card_id is a Keyword-indexed field carrying 30 distinct values -- far above this limit. + var values = await Port().ReadAsync("card_id", 5, TestContext.Current.CancellationToken); + + Assert.Equal(5, values.Count); + } + + [QdrantFact] + public async Task ReadAsync_PathWithNoKeywordIndex_ThrowsAndNamesThePath() + { + // "body" carries no payload index at all in this corpus. + var ex = await Assert.ThrowsAsync( + async () => await Port().ReadAsync("body", 100, TestContext.Current.CancellationToken)); + + Assert.Equal(StatusCode.InvalidArgument, ex.StatusCode); + Assert.Contains("body", ex.Message, StringComparison.Ordinal); + } + + [QdrantFact] + public async Task ReadAsync_WildcardValueComesBackAsAnOrdinaryValue() + { + var client = QdrantServer.CreateClient(); + var collection = $"facet-vocab-wildcard-{Guid.NewGuid():N}"; + + try + { + await client.CreateCollectionAsync( + collection, + vectorsConfig: new VectorParamsMap + { + Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, + }, + cancellationToken: TestContext.Current.CancellationToken); + await client.CreatePayloadIndexAsync( + collection, + "facets.brand", + PayloadSchemaType.Keyword, + cancellationToken: TestContext.Current.CancellationToken); + + var points = new[] + { + WildcardCard("card-1", brand: "*"), + WildcardCard("card-2", brand: "sole"), + }; + await client.UpsertAsync(collection, points, cancellationToken: TestContext.Current.CancellationToken); + + var port = new QdrantKnowledgeStore( + new QdrantSearchChannel(client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Collection = collection, + Scoped = false, + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + }); + + var values = await port.ReadAsync("facets.brand", 100, TestContext.Current.CancellationToken); + + Assert.Contains("*", values); + Assert.Contains("sole", values); + } + finally + { + await client.DeleteCollectionAsync(collection, cancellationToken: TestContext.Current.CancellationToken); + client.Dispose(); + } + } + + private static PointStruct WildcardCard(string cardId, string brand) + { + var point = new PointStruct + { + Id = new PointId { Uuid = Guid.NewGuid().ToString() }, + Vectors = new Vectors + { + Vectors_ = new NamedVectors { Vectors = { ["dense"] = KbShapedCorpus.QueryVector() } }, + }, + }; + + point.Payload["card_id"] = cardId; + point.Payload["body"] = $"{cardId} body"; + point.Payload["facets"] = new Value + { + StructValue = new Struct + { + Fields = { ["brand"] = new Value { StringValue = brand } }, + }, + }; + + return point; + } + + private QdrantKnowledgeStore Port() => new( + new QdrantSearchChannel(_corpus.Client), + new FakeEmbeddingGenerator(KbShapedCorpus.QueryVector()), + new QdrantKnowledgeStoreOptions + { + Collection = _corpus.Name, + Scoped = false, + VectorName = "dense", + 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..f99a66c3 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/CapturingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/CapturingSearchChannel.cs @@ -76,4 +76,8 @@ public Task> ScrollAsync( ScrollFilter = filter; return Task.FromResult(_fetched); } + + public Task> FacetAsync( + string collection, string key, ulong limit, CancellationToken cancellationToken) => + throw new NotSupportedException("No test here drives a facet read; use QdrantSearchChannel against a live server."); } 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..2c0d9afe 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/HangingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/HangingSearchChannel.cs @@ -29,4 +29,11 @@ public async Task> ScrollAsync( await Task.Delay(_delay, cancellationToken).ConfigureAwait(false); return []; } + + public async Task> FacetAsync( + string collection, string key, ulong 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..aad035a3 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/RecordingSearchChannel.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/RecordingSearchChannel.cs @@ -35,4 +35,8 @@ public Task> RetrieveAsync( 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> FacetAsync( + string collection, string key, ulong limit, CancellationToken cancellationToken) => + throw new NotSupportedException("These tests drive links.lookup: direct, which never facets."); } diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs index ea7d5216..abad9f9b 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeStoreTests.cs @@ -132,6 +132,25 @@ public void Options_LeftAtTheirDefaults_CarryTheValuesTheDesignNames() Assert.Null(options.ScopeTemplate); } + [Fact] + public async Task ReadAsync_NegativeLimit_Throws() + { + // limit becomes (ulong)limit right below the guard; without it, a negative int wraps into a + // huge facet request instead of failing the way a public port method should. + var store = new QdrantKnowledgeStore( + new CapturingSearchChannel([]), + new FakeEmbeddingGenerator(1f), + new QdrantKnowledgeStoreOptions + { + Collection = "anything", + Scoped = false, + Fields = new KnowledgeFieldsConfiguration { Body = "body" }, + }); + + await Assert.ThrowsAsync( + async () => await store.ReadAsync("facets.brand", -1, TestContext.Current.CancellationToken)); + } + [QdrantFact] public async Task SearchAsync_LookalikeIdentifier_RanksTheIdentifierCardFirst() { diff --git a/tests/AgentCore.TestSupport/TextSearchProviderInternals.cs b/tests/AgentCore.TestSupport/TextSearchProviderInternals.cs new file mode 100644 index 00000000..3e483b5b --- /dev/null +++ b/tests/AgentCore.TestSupport/TextSearchProviderInternals.cs @@ -0,0 +1,58 @@ +using System.Reflection; +using Microsoft.Agents.AI; + +namespace AgentCore.TestSupport; + +/// +/// Reaches the search delegate a was built around. +/// +/// +/// The delegate is the only way to drive a bound provider uniformly across both +/// SearchTime modes: under OnDemandFunctionCalling the framework never calls it before +/// the model does, and the provider's own SearchAsync wraps the answer into a formatted +/// string rather than the raw result list a test needs to inspect. It lives behind a private field, +/// so this is reflection — verified against Microsoft.Agents.AI 1.17.0. +/// +public static class TextSearchProviderInternals +{ + /// Reads the provider's own search delegate. + /// A provider built by the knowledge factory. + /// The delegate, ready to call. + /// is . + /// is not a . + /// + /// no longer declares the private field this depends on — a newer + /// Microsoft.Agents.AI changed its internals, and this helper needs updating for the new + /// shape rather than every caller seeing a bare . + /// + public static Func>> SearchDelegate( + AIContextProvider provider) + { + ArgumentNullException.ThrowIfNull(provider); + + if (provider is not TextSearchProvider search) + { + throw new ArgumentException( + $"expected a {nameof(TextSearchProvider)}, not a {provider.GetType().Name}.", nameof(provider)); + } + + var field = typeof(TextSearchProvider).GetField("_searchAsync", BindingFlags.NonPublic | BindingFlags.Instance) + ?? throw new InvalidOperationException( + "TextSearchProvider no longer has a private field named '_searchAsync'. " + + "Microsoft.Agents.AI changed its internals; update TextSearchProviderInternals for the new shape."); + + return (Func>>) + field.GetValue(search)!; + } + + /// Runs the provider's own search delegate and collects what it returned. + /// A provider built by the knowledge factory. + /// The search text. + /// The token the delegate receives, as a caller's own would be. + /// What the delegate returned. + public static async Task> SearchAsync( + AIContextProvider provider, + string query, + CancellationToken cancellationToken = default) + => [.. await SearchDelegate(provider)(query, cancellationToken).ConfigureAwait(false)]; +} From 3b699d71a76d6f4b68cb850cbdf2d07c8a21c52c Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Fri, 4 Sep 2026 14:33:13 -0600 Subject: [PATCH 3/4] feat: implement reasoning temperature validation and update OpenAI client handling --- .../Validation/ConfigurationValidator.cs | 1 + .../Validation/ReasoningTemperatureCheck.cs | 118 +++++++++++++++ .../Llm/OpenAI/OpenAiChatClientAdapter.cs | 21 +-- .../ReasoningTemperatureCheckTests.cs | 139 ++++++++++++++++++ .../Llm/OpenAiReasoningEffortTests.cs | 25 ++-- 5 files changed, 282 insertions(+), 22 deletions(-) create mode 100644 src/AgentCore.Application/Configuration/Validation/ReasoningTemperatureCheck.cs create mode 100644 tests/AgentCore.Application.Tests/Configuration/Validation/ReasoningTemperatureCheckTests.cs diff --git a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs index d184bc32..ef615820 100644 --- a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs +++ b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs @@ -90,6 +90,7 @@ public static ConfigurationValidationResult EvaluateStructure(AgentCoreConfigura var names = DeclaredNames.From(configuration); CheckReferences(configuration, names, errors); + ReasoningTemperatureCheck.Run(configuration, errors); CheckSlotWriters(configuration, errors); CheckKnowledgeScopeSlots(configuration, errors); CheckVocabularyAndAmbiguity(configuration, errors, warnings); diff --git a/src/AgentCore.Application/Configuration/Validation/ReasoningTemperatureCheck.cs b/src/AgentCore.Application/Configuration/Validation/ReasoningTemperatureCheck.cs new file mode 100644 index 00000000..326c5f5f --- /dev/null +++ b/src/AgentCore.Application/Configuration/Validation/ReasoningTemperatureCheck.cs @@ -0,0 +1,118 @@ +using System.Globalization; +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 call 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"; + + /// 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) + { + 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); + + var agents = configuration.Agents?.Items ?? []; + for (var 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); + } + } + + /// 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 ?? []) + { + if (entry.ReasoningEffort is { Length: > 0 } effort + && !string.Equals(effort, NoReasoning, StringComparison.OrdinalIgnoreCase)) + { + reasoning[entry.As] = effort; + } + } + + 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 + || temperature == ReasoningTemperature + || !reasoning.TryGetValue(model.Ref, out var 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, + }); + } + + /// 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.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs index 69c20147..289d19f9 100644 --- a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs +++ b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs @@ -10,7 +10,7 @@ using AgentCore.Application.Secrets; using Microsoft.Extensions.AI; using OpenAI; -using OpenAI.Chat; +using OpenAI.Responses; namespace AgentCore.Infrastructure.Llm.OpenAI; @@ -71,7 +71,7 @@ await secrets .RequireAsync(KnownSecrets.OpenAi, cancellationToken: cancellationToken) .ConfigureAwait(false))); - var client = _client.GetChatClient(entry.Model).AsIChatClient(); + var client = _client.GetResponsesClient().AsIChatClient(entry.Model); return entry.ReasoningEffort is { Length: > 0 } effort ? WithReasoningEffort(client, effort) : client; } @@ -88,7 +88,10 @@ internal static IChatClient WithReasoningEffort(IChatClient client, string effor return client .AsBuilder() .ConfigureOptions(options => options.RawRepresentationFactory ??= - _ => new ChatCompletionOptions { ReasoningEffortLevel = level }) + _ => new CreateResponseOptions + { + ReasoningOptions = new ResponseReasoningOptions { ReasoningEffortLevel = level }, + }) .Build(); } @@ -96,14 +99,14 @@ internal static IChatClient WithReasoningEffort(IChatClient client, string effor /// The value the document wrote. /// The vendor level. /// The value is not one this vendor knows. - private static ChatReasoningEffortLevel Level(string effort) + private static ResponseReasoningEffortLevel Level(string effort) => effort.ToLowerInvariant() switch { - "none" => ChatReasoningEffortLevel.None, - "minimal" => ChatReasoningEffortLevel.Minimal, - "low" => ChatReasoningEffortLevel.Low, - "medium" => ChatReasoningEffortLevel.Medium, - "high" => ChatReasoningEffortLevel.High, + "none" => ResponseReasoningEffortLevel.None, + "minimal" => ResponseReasoningEffortLevel.Minimal, + "low" => ResponseReasoningEffortLevel.Low, + "medium" => ResponseReasoningEffortLevel.Medium, + "high" => ResponseReasoningEffortLevel.High, _ => throw new ConfigurationLoadException(new ConfigurationError { Pointer = "/providers/llm", diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/ReasoningTemperatureCheckTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/ReasoningTemperatureCheckTests.cs new file mode 100644 index 00000000..ad778083 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/ReasoningTemperatureCheckTests.cs @@ -0,0 +1,139 @@ +using AgentCore.Application.Configuration.Parsing; +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 +{ + [Fact] + public void AReasoningEntryWithATemperature_FailsAndNamesBothKeys() + { + var error = Assert.Single(Evaluate(Document("low", "temperature: 0.2"))); + + Assert.Equal("/agents/items/0/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"))); + + [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 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 TheEffortOfAnotherEntry_DoesNotReachThisReference() + { + const string document = """ + apiVersion: agentcore/v1 + name: two-entries + agents: + items: + - { id: greeter, model: { ref: fill, temperature: 0.2 } } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + llm: + - { kind: openai, model: gpt-5.6-luna, as: reply, reasoningEffort: high } + - { kind: openai, model: gpt-4.1-mini, as: fill } + """; + + Assert.Empty(Evaluate(document)); + } + + [Fact] + public void ATitlerAndAToolAndTheAgentDefaults_AreCheckedToo() + { + const string document = """ + apiVersion: agentcore/v1 + name: every-holder + tools: + - { id: draw, kind: builtin, uses: ui.draw, model: { ref: reply, temperature: 0.2 } } + agents: + defaults: + model: { ref: reply, temperature: 0.2 } + items: + - { id: greeter } + titler: + model: { ref: reply, temperature: 0.2 } + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + llm: + - { kind: openai, model: gpt-5.6-luna, as: reply, reasoningEffort: low } + """; + + Assert.Equal( + ["/agents/defaults/model/temperature", "/titler/model/temperature", "/tools/0/model/temperature"], + Evaluate(document).Select(static error => error.Pointer).Order(StringComparer.Ordinal).ToArray()); + } + + /// 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)); + + 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) + => $$""" + apiVersion: agentcore/v1 + name: reasoning + agents: + items: + - id: greeter + model: + ref: reply + {{temperature ?? ""}} + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + llm: + - kind: openai + model: gpt-5.6-luna + as: reply + {{(effort is null ? "" : $"reasoningEffort: {effort}")}} + """; +} diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs index aa095eca..842563eb 100644 --- a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs @@ -6,8 +6,7 @@ using AgentCore.Infrastructure.Llm.OpenAI; using AgentCore.TestSupport; using Microsoft.Extensions.AI; -using ChatCompletionOptions = OpenAI.Chat.ChatCompletionOptions; -using ChatReasoningEffortLevel = OpenAI.Chat.ChatReasoningEffortLevel; +using OpenAI.Responses; using Xunit; namespace AgentCore.Infrastructure.Tests.Llm; @@ -17,10 +16,10 @@ namespace AgentCore.Infrastructure.Tests.Llm; /// /// /// -/// A reasoning model refuses function tools on the chat-completions path unless the value is -/// none. Without this setting, the first agent that lists a tool fails every turn with a -/// vendor 400 naming reasoning_effort — and the log calls it a tool that failed four times, -/// which is not what happened. +/// 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. @@ -41,14 +40,14 @@ public async Task EveryValueTheSchemaAllows_ReachesTheRequestTheVendorSees(strin var client = OpenAiChatClientAdapter.WithReasoningEffort(inner, effort); await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); - var raw = Assert.IsType( + var raw = Assert.IsType( inner.Seen!.RawRepresentationFactory!(inner)); - Assert.Equal(effort, raw.ReasoningEffortLevel.ToString()); + Assert.Equal(effort, raw.ReasoningOptions!.ReasoningEffortLevel.ToString()); } [Fact] - public async Task TheValueThatLetsAReasoningModelUseFunctionTools_IsTheOneNamedNone() + 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. @@ -57,10 +56,10 @@ public async Task TheValueThatLetsAReasoningModelUseFunctionTools_IsTheOneNamedN var client = OpenAiChatClientAdapter.WithReasoningEffort(inner, "none"); await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); - var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); - Assert.Equal(ChatReasoningEffortLevel.None, raw.ReasoningEffortLevel); - Assert.Equal("none", ChatReasoningEffortLevel.None.ToString()); + Assert.Equal(ResponseReasoningEffortLevel.None, raw.ReasoningOptions!.ReasoningEffortLevel); + Assert.Equal("none", ResponseReasoningEffortLevel.None.ToString()); } [Fact] @@ -68,7 +67,7 @@ public async Task RawOptionsTheCallerBuiltItself_AreLeftAlone() { // A default for the entry, not an override of the call. CapturingChatClient inner = new(); - ChatCompletionOptions mine = new(); + CreateResponseOptions mine = new(); var client = OpenAiChatClientAdapter.WithReasoningEffort(inner, "none"); await client.GetResponseAsync( From c7f8d6544f3a36a9e6114867712a5c55ede49bcb Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Fri, 4 Sep 2026 18:51:07 -0600 Subject: [PATCH 4/4] feat: refactor OpenAiChatClientAdapter to use WithResponseDefaults for client creation --- .../Llm/OpenAI/OpenAiChatClientAdapter.cs | 48 +++++++------- .../Llm/OpenAiReasoningEffortTests.cs | 62 +++++++++++++++---- 2 files changed, 78 insertions(+), 32 deletions(-) diff --git a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs index 289d19f9..15489331 100644 --- a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs +++ b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs @@ -50,15 +50,6 @@ public sealed class OpenAiChatClientAdapter : IChatClientAdapter public string Kind => ProviderKind; /// Builds the client of one entry, reading the key on the first build only. - /// The entry, whose kind named this adapter. - /// The resolver chain, or to read the environment only. - /// Cancels the key read. - /// The client. The composite owns and disposes it. - /// Neither the chain nor the environment holds a key. - /// - /// The composite builds sequentially while the host starts, so this method is not called from - /// two threads at once and the one-client cache needs no lock. - /// public async ValueTask CreateClientAsync( LlmProviderConfiguration entry, ISecretResolverPort? secrets, @@ -73,25 +64,40 @@ await secrets var client = _client.GetResponsesClient().AsIChatClient(entry.Model); - return entry.ReasoningEffort is { Length: > 0 } effort ? WithReasoningEffort(client, effort) : client; + return WithResponseDefaults(client, entry.ReasoningEffort); } - /// Puts reasoning_effort on every request this client sends. - /// The client of one entry. - /// The value the document wrote. - /// The client the factory hands out. - /// The value is not one this vendor knows. - internal static IChatClient WithReasoningEffort(IChatClient client, string effort) + /// Puts store and reasoning_effort on every request this client sends. + internal static IChatClient WithResponseDefaults(IChatClient client, string? effort) { - var level = Level(effort); + var level = effort is { Length: > 0 } value ? Level(value) : (ResponseReasoningEffortLevel?)null; return client .AsBuilder() - .ConfigureOptions(options => options.RawRepresentationFactory ??= - _ => new CreateResponseOptions + .ConfigureOptions(options => + { + var caller = options.RawRepresentationFactory; + + options.RawRepresentationFactory = inner => { - ReasoningOptions = new ResponseReasoningOptions { ReasoningEffortLevel = level }, - }) + if (caller?.Invoke(inner) is not CreateResponseOptions raw) + { + raw = new CreateResponseOptions(); + } + + raw.StoredOutputEnabled ??= false; + + if (level is { } chosen) + { + raw.ReasoningOptions ??= new ResponseReasoningOptions + { + ReasoningEffortLevel = chosen, + }; + } + + return raw; + }; + }) .Build(); } diff --git a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs index 842563eb..c4ff7d3d 100644 --- a/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Llm/OpenAiReasoningEffortTests.cs @@ -37,7 +37,7 @@ public async Task EveryValueTheSchemaAllows_ReachesTheRequestTheVendorSees(strin { CapturingChatClient inner = new(); - var client = OpenAiChatClientAdapter.WithReasoningEffort(inner, effort); + var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort); await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); var raw = Assert.IsType( @@ -53,7 +53,7 @@ public async Task TheLevelThatSendsNoReasoningAtAll_IsTheOneNamedNone() // provider. The SDK marks this type for evaluation (OPENAI001); this is what watches it. CapturingChatClient inner = new(); - var client = OpenAiChatClientAdapter.WithReasoningEffort(inner, "none"); + var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, "none"); await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); @@ -63,26 +63,68 @@ public async Task TheLevelThatSendsNoReasoningAtAll_IsTheOneNamedNone() } [Fact] - public async Task RawOptionsTheCallerBuiltItself_AreLeftAlone() + public async Task RawOptionsTheCallerBuiltItself_KeepTheValuesTheyAlreadyHold() { - // A default for the entry, not an override of the call. + // A default for the entry, not an override of the call. The caller's own object is the one + // the vendor sees, and every value it already carries survives. CapturingChatClient inner = new(); - CreateResponseOptions mine = new(); + CreateResponseOptions mine = new() + { + ReasoningOptions = new ResponseReasoningOptions + { + ReasoningEffortLevel = ResponseReasoningEffortLevel.High, + }, + StoredOutputEnabled = true, + }; - var client = OpenAiChatClientAdapter.WithReasoningEffort(inner, "none"); + 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); + } + + [Theory] + [InlineData("high")] + [InlineData(null)] + public async Task EveryRequest_TellsTheVendorNotToStoreTheConversation(string? effort) + { + // The call 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(); + + var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, effort); + await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); + + var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + + 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(); + + var client = OpenAiChatClientAdapter.WithResponseDefaults(inner, null); + await client.GetResponseAsync("hi", cancellationToken: TestContext.Current.CancellationToken); + + var raw = Assert.IsType(inner.Seen!.RawRepresentationFactory!(inner)); + + Assert.Null(raw.ReasoningOptions); } [Fact] public void AValueThisVendorDoesNotKnow_FailsAndSaysWhatIsAllowed() { var failure = Assert.Throws( - () => OpenAiChatClientAdapter.WithReasoningEffort(new CapturingChatClient(), "exhaustive")); + () => OpenAiChatClientAdapter.WithResponseDefaults(new CapturingChatClient(), "exhaustive")); Assert.Contains(failure.Errors, error => error.Pointer == "/providers/llm"); Assert.Contains("exhaustive", failure.Message, StringComparison.Ordinal); @@ -90,10 +132,8 @@ public void AValueThisVendorDoesNotKnow_FailsAndSaysWhatIsAllowed() } [Fact] - public async Task AnEntryThatNamesNoEffort_IsNotWrappedAtAll() + public async Task AnEntryThatNamesNoEffort_StillCarriesTheStoreFlag() { - // Omitting it must not start sending a value the vendor would otherwise have chosen for - // itself. The adapter returns the bare client. MapSecretResolver secrets = new MapSecretResolver() .With(OpenAiChatClientAdapter.ApiKeySecretName, "sk-not-a-real-key"); @@ -108,7 +148,7 @@ public async Task AnEntryThatNamesNoEffort_IsNotWrappedAtAll() TestContext.Current.CancellationToken); // A wrapped client answers GetService for the configuring middleware; a bare one does not. - Assert.Null(client.GetService(typeof(ConfigureOptionsChatClient))); + Assert.NotNull(client.GetService(typeof(ConfigureOptionsChatClient))); } /// Records the options it was called with, and answers nothing.