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/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/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 817aa5a1..1be4229a 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; }
@@ -214,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; }
@@ -233,10 +265,52 @@ 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;
}
+///
+/// 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 84308e05..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": [
@@ -1147,6 +1184,57 @@
"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."
+ }
+ }
+ },
+ "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."
}
}
},
@@ -1199,8 +1287,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..ef615820 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.
@@ -82,7 +90,10 @@ 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);
CheckGuardRules(configuration, errors);
CheckExclusivity(configuration, errors, warnings);
CheckReachability(configuration, errors);
@@ -142,6 +153,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.
@@ -372,6 +409,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.
@@ -498,6 +559,309 @@ 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(
+ 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(
+ 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 not { } widened)
+ {
+ errors.Add(Reference(
+ 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)
+ {
+ 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 (!configuration.State.TryGetValue(name, out var slot))
+ {
+ errors.Add(Reference(
+ Pointer.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 } && slot.Vocabulary is null)
+ {
+ errors.Add(Reference(
+ ConfigurationError.AppendPointer(pointer, "enum"),
+ $"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.
// ---------------------------------------------------------------------------------------------
@@ -990,6 +1354,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 };
@@ -1033,6 +1436,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/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.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..0e47a79d 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,50 @@ 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);
+
+ /// §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/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/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/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/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
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.";
-
///
/// The scope an agent that declares scoped: false searches under.
///
@@ -86,68 +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);
}
- var shown = Kept(cards, knowledge);
+ // §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 } scope)
+ {
+ 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.
@@ -212,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 };
}
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/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/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 deaff9c4..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!
@@ -480,9 +530,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!
@@ -581,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
@@ -632,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
@@ -888,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
@@ -982,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
@@ -1032,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
@@ -1042,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
@@ -1072,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!>
@@ -1166,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