Skip to content
Merged
  •  
  •  
  •  
22 changes: 22 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4

[*.{csproj,props,targets,json,xml,yaml,yml,md}]
indent_size = 2

[*.cs]
# Every IDE style rule at the Roslyn default preference, raised from hidden to suggestion so that
# dotnet format applies it and SonarQube reports whatever is left.
dotnet_analyzer_diagnostic.category-Style.severity = suggestion

# Off because it folds every guard before a return into a ternary, and a second guard then nests
# one ternary inside another, which SonarQube S3358 forbids. Sonar wins.
dotnet_style_prefer_conditional_expression_over_return = false
dotnet_style_prefer_conditional_expression_over_assignment = false
21 changes: 2 additions & 19 deletions config/example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
# 3. extractor the model call that fills the extractor slots
# 4. guards named JSONLogic rules the stage machine tests
# 5. tools what an agent may call
# 6. agents models, prompts, knowledge, compaction
# 6. agents models, prompts, knowledge
# 7. entries what a caller reaches: a stage machine or one agent
# 8. providers adapters: llm, conversation, speech, telephony, moderation, embeddings, knowledge,
# telemetry
Expand Down Expand Up @@ -227,7 +227,7 @@ tools:


# =============================================================================================
# 6. agents: models, prompts, knowledge, compaction
# 6. agents: models, prompts, knowledge
# =============================================================================================
#
# defaults: applies to every item. An item overrides a key by declaring it.
Expand Down Expand Up @@ -269,23 +269,6 @@ agents:
# whole corpus.
knowledge: { mode: prefetch, limit: 5, citations: false }

# Bounds the conversation an agent carries. Every strategy is deterministic: the same messages
# give the same result. There is no summarization on purpose. A resumed conversation rebuilds from
# the replayed words, and a model-written summary would give one conversation two histories.
# strategy truncate | sliding_window | tool_result | context_window
# tool_result folds old function-tool groups into one short line each.
# context_window folds first, then truncates whole groups.
# trigger exactly ONE of tokens, messages, turns, groups. Zero or two is a load
# error.
# keep the newest groups the strategy never touches.
# foldResultChars how much of a tool result one fold keeps.
# There is no per-agent opt-out. An item with no block inherits this one. To compact some
# agents only, declare the block on those items instead of here.
#
# context_window, not tool_result, here: the analyst below carries search, a hosted tool.
# tool_result folds function tools only, so a hosted tool's results would grow for ever.
compaction: { strategy: context_window, trigger: { messages: 40 }, keep: 6, foldResultChars: 300 }

items:
# Voice, scripted. One round trip, no source labels spoken. Inherit knowledge from defaults.
- { id: greeter, instructions: "<stage delta>", tools: [] }
Expand Down
89 changes: 45 additions & 44 deletions src/AgentCore.Application/Audit/AuditConversationObserver.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,57 +2,58 @@
using AgentCore.Application.Runtime;
using AgentCore.Domain.Audit;

namespace AgentCore.Application.Audit;

/// <summary>
/// Turns the durable facts of a call into the append-only chain of D23.
/// </summary>
internal sealed class AuditConversationObserver : IConversationObserver
namespace AgentCore.Application.Audit
{
private readonly IAuditSinkPort _sink;

/// <summary>Creates the observer that writes the chain.</summary>
/// <param name="sink">Where the rows go.</param>
/// <exception cref="ArgumentNullException"><paramref name="sink"/> is <see langword="null"/>.</exception>
public AuditConversationObserver(IAuditSinkPort sink)
/// <summary>
/// Turns the durable facts of a call into the append-only chain of D23.
/// </summary>
internal sealed class AuditConversationObserver : IConversationObserver
{
ArgumentNullException.ThrowIfNull(sink);
private readonly IAuditSinkPort _sink;

_sink = sink;
}

/// <inheritdoc />
public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(conversationEvent);

// A diagnostic-only fact took no identity, so there is no row to write and nothing to report.
if (conversationEvent.EventId is not { } eventId)
/// <summary>Creates the observer that writes the chain.</summary>
/// <param name="sink">Where the rows go.</param>
/// <exception cref="ArgumentNullException"><paramref name="sink"/> is <see langword="null"/>.</exception>
public AuditConversationObserver(IAuditSinkPort sink)
{
return ValueTask.CompletedTask;
}
ArgumentNullException.ThrowIfNull(sink);

// The two enums are not interchangeable, and a value outside the closed set is dropped rather
// than thrown over: the turn loop pairs an identity with a stored kind, so this is unreachable
// for any event the session raises, and audit is a record of the conversation and never a part of it.
if (!ConversationEventKinds.TryGetAuditKind(conversationEvent.Kind, out AuditEventKind kind))
{
return ValueTask.CompletedTask;
_sink = sink;
}

AuditEvent auditEvent = new()
/// <inheritdoc />
public ValueTask OnConversationEventAsync(ConversationEvent conversationEvent, CancellationToken cancellationToken)
{
ConversationId = conversationEvent.ConversationId,
EventId = eventId,
Kind = kind,
OccurredAt = conversationEvent.OccurredAt,
TurnIndex = conversationEvent.TurnIndex,
AmendsEventId = conversationEvent.AmendsEventId,
Payload = conversationEvent.Payload,
};

// The token of the run belongs to the dispatcher, which passes CancellationToken.None: the
// enqueue belongs to the record of the conversation, not to a turn the caller may have cancelled.
return _sink.AppendAsync(auditEvent, cancellationToken);
ArgumentNullException.ThrowIfNull(conversationEvent);

// A diagnostic-only fact took no identity, so there is no row to write and nothing to report.
if (conversationEvent.EventId is not { } eventId)
{
return ValueTask.CompletedTask;
}

// The two enums are not interchangeable, and a value outside the closed set is dropped rather
// than thrown over: the turn loop pairs an identity with a stored kind, so this is unreachable
// for any event the session raises, and audit is a record of the conversation and never a part of it.
if (!ConversationEventKinds.TryGetAuditKind(conversationEvent.Kind, out AuditEventKind kind))
{
return ValueTask.CompletedTask;
}

AuditEvent auditEvent = new()
{
ConversationId = conversationEvent.ConversationId,
EventId = eventId,
Kind = kind,
OccurredAt = conversationEvent.OccurredAt,
TurnIndex = conversationEvent.TurnIndex,
AmendsEventId = conversationEvent.AmendsEventId,
Payload = conversationEvent.Payload,
};

// The token of the run belongs to the dispatcher, which passes CancellationToken.None: the
// enqueue belongs to the record of the conversation, not to a turn the caller may have cancelled.
return _sink.AppendAsync(auditEvent, cancellationToken);
}
}
}
85 changes: 43 additions & 42 deletions src/AgentCore.Application/Audit/AuditSinkFactory.cs
Original file line number Diff line number Diff line change
Expand Up @@ -4,52 +4,53 @@
using AgentCore.Application.Ports;
using AgentCore.Application.Providers;

namespace AgentCore.Application.Audit;

/// <summary>
/// Opens the audit sink the document names, from the adapters the host registered.
/// </summary>
public static class AuditSinkFactory
namespace AgentCore.Application.Audit
{
/// <summary>The built-in kind, and the one a document that names no provider gets.</summary>
public const string MemoryKind = "memory";

/// <summary>What this seam conversations itself, so the shared selector writes its failures.</summary>
private static readonly VendorSeam Seam =
new("providers.audit", "/providers/audit/kind", "options.UseAuditSinks(...)", "sinks");

/// <summary>Opens the sink <c>providers.audit</c> names, or the built-in one.</summary>
/// <param name="configuration">The loaded document.</param>
/// <param name="secrets">The chain a credential resolves through, or <see langword="null"/>.</param>
/// <param name="adapters">The vendors this host supports.</param>
/// <param name="cancellationToken">Cancels the open.</param>
/// <returns>
/// The store, which is never <see langword="null"/>. It is the raw store and not a queue: the
/// caller wraps it in <see cref="QueuedAuditSink"/>, which is what keeps the append off the turn.
/// </returns>
/// <exception cref="ArgumentNullException">The configuration or the adapters are <see langword="null"/>.</exception>
/// <exception cref="ConfigurationLoadException">
/// The document names a <c>kind</c> no adapter serves, or a <c>kind</c> two adapters answer to.
/// </exception>
public static ValueTask<IAuditSinkPort> OpenAsync(
AgentCoreConfiguration configuration,
ISecretResolverPort? secrets,
IReadOnlyList<IAuditSinkAdapter> adapters,
CancellationToken cancellationToken = default)
/// <summary>
/// Opens the audit sink the document names, from the adapters the host registered.
/// </summary>
public static class AuditSinkFactory
{
ArgumentNullException.ThrowIfNull(configuration);
ArgumentNullException.ThrowIfNull(adapters);
/// <summary>The built-in kind, and the one a document that names no provider gets.</summary>
public const string MemoryKind = "memory";

/// <summary>What this seam conversations itself, so the shared selector writes its failures.</summary>
private static readonly VendorSeam Seam =
new("providers.audit", "/providers/audit/kind", "options.UseAuditSinks(...)", "sinks");

// The document named nothing, or it named the built-in kind, and the two mean the same
// thing: an absent block is read as kind: memory. Both are answered before the selector
// runs, so neither needs a registered adapter and neither can be taken over by one.
if (configuration.Providers?.Audit is not { } entry
|| string.Equals(entry.Kind, MemoryKind, StringComparison.OrdinalIgnoreCase))
/// <summary>Opens the sink <c>providers.audit</c> names, or the built-in one.</summary>
/// <param name="configuration">The loaded document.</param>
/// <param name="secrets">The chain a credential resolves through, or <see langword="null"/>.</param>
/// <param name="adapters">The vendors this host supports.</param>
/// <param name="cancellationToken">Cancels the open.</param>
/// <returns>
/// The store, which is never <see langword="null"/>. It is the raw store and not a queue: the
/// caller wraps it in <see cref="QueuedAuditSink"/>, which is what keeps the append off the turn.
/// </returns>
/// <exception cref="ArgumentNullException">The configuration or the adapters are <see langword="null"/>.</exception>
/// <exception cref="ConfigurationLoadException">
/// The document names a <c>kind</c> no adapter serves, or a <c>kind</c> two adapters answer to.
/// </exception>
public static ValueTask<IAuditSinkPort> OpenAsync(
AgentCoreConfiguration configuration,
ISecretResolverPort? secrets,
IReadOnlyList<IAuditSinkAdapter> adapters,
CancellationToken cancellationToken = default)
{
return ValueTask.FromResult<IAuditSinkPort>(new InMemoryAuditSink());
}
ArgumentNullException.ThrowIfNull(configuration);
ArgumentNullException.ThrowIfNull(adapters);

// The document named nothing, or it named the built-in kind, and the two mean the same
// thing: an absent block is read as kind: memory. Both are answered before the selector
// runs, so neither needs a registered adapter and neither can be taken over by one.
if (configuration.Providers?.Audit is not { } entry
|| string.Equals(entry.Kind, MemoryKind, StringComparison.OrdinalIgnoreCase))
{
return ValueTask.FromResult<IAuditSinkPort>(new InMemoryAuditSink());
}

var adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam);
return adapter.OpenAsync(entry, secrets, cancellationToken);
IAuditSinkAdapter adapter = VendorAdapterSelector.Select(entry.Kind, adapters, Seam);
return adapter.OpenAsync(entry, secrets, cancellationToken);
}
}
}
77 changes: 39 additions & 38 deletions src/AgentCore.Application/Audit/Memory/InMemoryAuditSink.cs
Original file line number Diff line number Diff line change
@@ -1,56 +1,57 @@
using AgentCore.Application.Ports;
using AgentCore.Domain.Audit;

namespace AgentCore.Application.Audit.Memory;

/// <summary>
/// The sink that keeps every event in a list.
/// </summary>
public sealed class InMemoryAuditSink : IAuditSinkPort
namespace AgentCore.Application.Audit.Memory
{
private readonly Lock _gate = new();
/// <summary>
/// The sink that keeps every event in a list.
/// </summary>
public sealed class InMemoryAuditSink : IAuditSinkPort
{
private readonly Lock _gate = new();

private readonly List<AuditEvent> _events = [];
private readonly List<AuditEvent> _events = [];

/// <summary>Gets the events this sink accepted, in the order they arrived.</summary>
public IReadOnlyList<AuditEvent> Events
{
get
/// <summary>Gets the events this sink accepted, in the order they arrived.</summary>
public IReadOnlyList<AuditEvent> Events
{
lock (_gate)
get
{
return [.. _events];
lock (_gate)
{
return [.. _events];
}
}
}
}

/// <summary>
/// Reads back the events of one conversation, oldest first.
/// </summary>
/// <param name="conversationId">The id of the conversation.</param>
/// <returns>The events of that conversation, in the order they arrived.</returns>
/// <exception cref="ArgumentNullException"><paramref name="conversationId"/> is <see langword="null"/>.</exception>
public IReadOnlyList<AuditEvent> EventsOf(string conversationId)
{
ArgumentNullException.ThrowIfNull(conversationId);

lock (_gate)
/// <summary>
/// Reads back the events of one conversation, oldest first.
/// </summary>
/// <param name="conversationId">The id of the conversation.</param>
/// <returns>The events of that conversation, in the order they arrived.</returns>
/// <exception cref="ArgumentNullException"><paramref name="conversationId"/> is <see langword="null"/>.</exception>
public IReadOnlyList<AuditEvent> EventsOf(string conversationId)
{
return [.. _events.Where(item => string.Equals(item.ConversationId, conversationId, StringComparison.Ordinal))];
}
}
ArgumentNullException.ThrowIfNull(conversationId);

/// <inheritdoc />
public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(auditEvent);
AuditEventVocabulary.Validate(auditEvent);
lock (_gate)
{
return [.. _events.Where(item => string.Equals(item.ConversationId, conversationId, StringComparison.Ordinal))];
}
}

lock (_gate)
/// <inheritdoc />
public ValueTask AppendAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default)
{
_events.Add(auditEvent);
}
ArgumentNullException.ThrowIfNull(auditEvent);
AuditEventVocabulary.Validate(auditEvent);

lock (_gate)
{
_events.Add(auditEvent);
}

return ValueTask.CompletedTask;
return ValueTask.CompletedTask;
}
}
}
Loading
Loading