@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentSpec.cs

@@ -0,0 +1,91 @@
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Morph.AiKit.Agents;
+
+/// <summary>
+/// O agente <b>como dado</b>: tudo o que a <c>AgentFactory</c> (T10) precisa para
+/// materializar um <c>AIAgent</c>, e nada mais. Nao tem comportamento de execucao, nao
+/// abre conexao, nao le configuracao — o que permite descrever um agente em teste, em
+/// JSON ou em banco sem arrastar infraestrutura junto.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>O modelo nao aparece aqui.</b> So o <see cref="Alias"/>, que e resolvido pelo
+/// <c>ModelRegistry</c>. E a regra do standard <c>ai-agents-providers-model-registry</c>:
+/// agentes referenciam alias, nunca id de modelo — trocar de provider e mudanca de um
+/// arquivo so.
+/// </para>
+/// </remarks>
+public sealed record AgentSpec
+{
+    private readonly string _alias = string.Empty;
+    private readonly string _instructions = string.Empty;
+
+    /// <summary>
+    /// Chave no <c>ModelRegistry</c>. Nunca um id de modelo.
+    /// Vazio ou so espaco e rejeitado na construcao: um alias em branco viraria uma falha
+    /// de resolucao ilegivel varias camadas adiante.
+    /// </summary>
+    public required string Alias
+    {
+        get => _alias;
+        init
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(value, nameof(Alias));
+            _alias = value;
+        }
+    }
+
+    /// <summary>Prompt de sistema do agente. Vazio ou so espaco e rejeitado na construcao.</summary>
+    public required string Instructions
+    {
+        get => _instructions;
+        init
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(value, nameof(Instructions));
+            _instructions = value;
+        }
+    }
+
+    /// <summary>
+    /// Protocolo desta spec. <b>Nulo = usa o <c>api:</c> do alias</b> — o caso normal.
+    /// Preenchido, vence o alias (ver <see cref="ResolveApi"/>).
+    /// </summary>
+    public AgentApi? Api { get; init; }
+
+    /// <summary>Tools do agente. Vazio por padrao — nunca nulo.</summary>
+    public IReadOnlyList<AITool> Tools { get; init; } = [];
+
+    /// <summary>
+    /// Schema JSON da saida estruturada. Nulo = saida livre.
+    /// <para>
+    /// <b>Armadilha de tempo de vida:</b> um <see cref="JsonElement"/> so e valido enquanto
+    /// o <see cref="JsonDocument"/> que o originou estiver vivo. Guarde aqui um
+    /// <see cref="JsonElement.Clone"/> quando o documento for descartado — senao o schema
+    /// morre silenciosamente entre a montagem da spec e o uso dela.
+    /// </para>
+    /// </summary>
+    public JsonElement? OutputSchema { get; init; }
+
+    /// <summary>Bag unico de opcoes. Nunca nulo; o default nao envia opcao nenhuma.</summary>
+    public AgentSpecOptions Options { get; init; } = new();
+
+    /// <summary>Nome legivel do agente (telemetria, logs). Nulo = sem nome.</summary>
+    public string? Name { get; init; }
+
+    /// <summary>Descricao legivel do agente. Nulo = sem descricao.</summary>
+    public string? Description { get; init; }
+
+    /// <summary>
+    /// Precedencia entre o <c>api:</c> da spec e o <c>api:</c> do alias, num lugar so.
+    /// <b>A spec vence quando presente; o alias vence quando a spec e nula.</b>
+    /// </summary>
+    /// <remarks>
+    /// A regra mora aqui, e nao dentro da <c>AgentFactory</c>, porque divergencia silenciosa
+    /// entre spec e registry e exatamente o bug que o <c>api:</c> por alias existe para
+    /// eliminar — e uma regra copiada em dois lugares e uma regra que ja divergiu.
+    /// </remarks>
+    /// <param name="aliasApi">O <c>api:</c> declarado no alias resolvido.</param>
+    public AgentApi ResolveApi(AgentApi aliasApi) => Api ?? aliasApi;
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentSpecOptions.cs

@@ -0,0 +1,181 @@
+using Microsoft.Extensions.AI;
+
+namespace Morph.AiKit.Agents;
+
+/// <summary>
+/// UM UNICO bag de opcoes do agente — a forma copiada do <c>AgentFrameworkToolkit</c>
+/// sem o pacote (decisao D2). Em vez de N objetos de configuracao espalhados por
+/// camadas, tudo o que um agente pode ajustar vive aqui, como dado.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Regra estrutural, e a razao de o tipo existir:</b> toda propriedade e nula por
+/// padrao, e <b>nulo significa "nao envia ao provider"</b> — nunca "envia o default do
+/// framework". E isso que impede o kit de mudar, por omissao, o comportamento de um
+/// modelo. O canario da regra e
+/// <c>AgentSpecTests.FreshOptionsProduceChatOptionsIndistinguishableFromPristine</c>:
+/// uma <see cref="AgentSpecOptions"/> recem-construida produz um <see cref="ChatOptions"/>
+/// indistinguivel de <c>new ChatOptions()</c>, propriedade por propriedade, por reflexao.
+/// </para>
+/// <para><b>Duas familias de opcao convivem aqui, e a fronteira e explicita:</b></para>
+/// <list type="table">
+///   <listheader><term>Familia</term><description>Para onde vai</description></listheader>
+///   <item>
+///     <term>Nivel de requisicao</term>
+///     <description>
+///       <see cref="Temperature"/>, <see cref="TopP"/>, <see cref="MaxOutputTokens"/>,
+///       <see cref="Seed"/>, <see cref="StopSequences"/>, <see cref="ToolMode"/>,
+///       <see cref="ReasoningEffort"/> e <see cref="ServiceTier"/> viram
+///       <see cref="ChatOptions"/> em <see cref="ApplyTo"/>.
+///     </description>
+///   </item>
+///   <item>
+///     <term>Nivel de agente / pipeline</term>
+///     <description>
+///       <see cref="MaxToolIterations"/>, <see cref="AllowConcurrentToolInvocation"/>,
+///       <see cref="TimeoutSeconds"/> e <see cref="EnableSensitiveTelemetry"/> NAO existem
+///       em <see cref="ChatOptions"/>. Sao lidas diretamente pela <c>AgentFactory</c> (T10)
+///       ao montar o pipeline e pela telemetria (T12). O teste
+///       <c>AgentLevelKnobsNeverLeakIntoChatOptions</c> pina essa fronteira.
+///     </description>
+///   </item>
+/// </list>
+/// </remarks>
+public sealed record AgentSpecOptions
+{
+    /// <summary>
+    /// Chave usada em <see cref="ChatOptions.AdditionalProperties"/> para transportar
+    /// <see cref="ServiceTier"/>. Ver a nota de fato em <see cref="ServiceTier"/>.
+    /// </summary>
+    public const string ServiceTierPropertyName = "service_tier";
+
+    /// <summary>Amostragem. Nulo = o provider decide.</summary>
+    public float? Temperature { get; init; }
+
+    /// <summary>Nucleus sampling. Nulo = o provider decide.</summary>
+    public float? TopP { get; init; }
+
+    /// <summary>Teto de tokens de saida. Nulo = o provider decide.</summary>
+    public int? MaxOutputTokens { get; init; }
+
+    /// <summary>Semente de amostragem, quando o provider suporta. Nulo = nao envia.</summary>
+    public long? Seed { get; init; }
+
+    /// <summary>
+    /// Sequencias de parada. Nulo = nao envia. Lista vazia NAO e tratada como nulo: e
+    /// enviada como veio. "Nulo nao envia; nao-nulo envia o que voce escreveu" e a regra
+    /// inteira, sem excecao escondida.
+    /// </summary>
+    public IReadOnlyList<string>? StopSequences { get; init; }
+
+    /// <summary>Modo de tool calling (<c>Auto</c>, <c>None</c>, <c>RequireAny</c>...). Nulo = nao envia.</summary>
+    public ChatToolMode? ToolMode { get; init; }
+
+    /// <summary>
+    /// Esforco de raciocinio. Tipado com o enum de primeira classe do
+    /// <c>Microsoft.Extensions.AI</c> 10.9.0 (<c>None/Low/Medium/High/ExtraHigh</c>) em vez
+    /// de string, porque e exatamente esse valor que o limite de tool calling da Chat
+    /// Completions cita — ver <c>ModelAliasConstraints.ToolCallingRequiresReasoningEffortNone</c>.
+    /// Nulo = nao envia: vale o default do provider, e qual e ele o kit NAO afirma saber.
+    /// </summary>
+    public Microsoft.Extensions.AI.ReasoningEffort? ReasoningEffort { get; init; }
+
+    /// <summary>
+    /// Tier de servico (ex.: <c>"flex"</c>, <c>"priority"</c>).
+    /// <b>Nota de fato, nao de gosto:</b> o <see cref="ChatOptions"/> do
+    /// <c>Microsoft.Extensions.AI</c> 10.9.0 NAO tem propriedade de service tier — apurado
+    /// por reflexao sobre o assembly do pin, nao por memoria. Quando definido, o valor
+    /// viaja em <see cref="ChatOptions.AdditionalProperties"/> sob a chave
+    /// <see cref="ServiceTierPropertyName"/>, e so chega ao fio se o adaptador do provider
+    /// ler dali ou se a <c>AgentFactory</c> montar um
+    /// <see cref="ChatOptions.RawRepresentationFactory"/>. Nulo = nao envia.
+    /// </summary>
+    public string? ServiceTier { get; init; }
+
+    /// <summary>
+    /// Teto de voltas de tool calling. <b>Nivel de agente</b>: vira
+    /// <c>FunctionInvokingChatClient.MaximumIterationsPerRequest</c> na T10, nunca
+    /// <see cref="ChatOptions"/>. Nulo = default do pipeline.
+    /// </summary>
+    public int? MaxToolIterations { get; init; }
+
+    /// <summary>
+    /// Permite invocar tools concorrentemente numa mesma volta. <b>Nivel de agente</b>
+    /// (<c>FunctionInvokingChatClient.AllowConcurrentInvocation</c>). Nulo = default do pipeline.
+    /// </summary>
+    public bool? AllowConcurrentToolInvocation { get; init; }
+
+    /// <summary>
+    /// Timeout da invocacao, em segundos. <b>Nivel de agente</b>: vira
+    /// <c>CancellationToken</c> na T10. Nulo = sem timeout proprio.
+    /// </summary>
+    public int? TimeoutSeconds { get; init; }
+
+    /// <summary>
+    /// Liga a captura de conteudo sensivel (prompt e resposta) nos spans.
+    /// <b>Nivel de agente</b> — insumo da T12. A diferenca entre nulo e <c>false</c> e
+    /// preservada de proposito: nulo e "nao opinei", <c>false</c> e "decidi que nao".
+    /// </summary>
+    public bool? EnableSensitiveTelemetry { get; init; }
+
+    /// <summary>
+    /// Produz um <see cref="ChatOptions"/> novo com — e SOMENTE com — as opcoes de nivel
+    /// de requisicao que foram definidas.
+    /// </summary>
+    public ChatOptions ToChatOptions() => ApplyTo(new ChatOptions());
+
+    /// <summary>
+    /// Aplica as opcoes de nivel de requisicao sobre um <see cref="ChatOptions"/> existente.
+    /// Propriedade nula aqui NAO toca no destino, o que permite a <c>AgentFactory</c>
+    /// preencher <c>Tools</c> e <c>ResponseFormat</c> antes ou depois sem risco de perde-los.
+    /// </summary>
+    /// <param name="options">Destino. Nao pode ser nulo.</param>
+    /// <returns>O proprio <paramref name="options"/>, para encadeamento.</returns>
+    public ChatOptions ApplyTo(ChatOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        if (Temperature is { } temperature)
+        {
+            options.Temperature = temperature;
+        }
+
+        if (TopP is { } topP)
+        {
+            options.TopP = topP;
+        }
+
+        if (MaxOutputTokens is { } maxOutputTokens)
+        {
+            options.MaxOutputTokens = maxOutputTokens;
+        }
+
+        if (Seed is { } seed)
+        {
+            options.Seed = seed;
+        }
+
+        if (StopSequences is not null)
+        {
+            options.StopSequences = [.. StopSequences];
+        }
+
+        if (ToolMode is not null)
+        {
+            options.ToolMode = ToolMode;
+        }
+
+        if (ReasoningEffort is { } effort)
+        {
+            options.Reasoning = new ReasoningOptions { Effort = effort };
+        }
+
+        if (ServiceTier is not null)
+        {
+            options.AdditionalProperties ??= new AdditionalPropertiesDictionary();
+            options.AdditionalProperties[ServiceTierPropertyName] = ServiceTier;
+        }
+
+        return options;
+    }
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/AiKitAssemblyMarker.cs

@@ -0,0 +1,14 @@
+namespace Morph.AiKit;
+
+/// <summary>
+/// Ancora de tipo do assembly. Existe para que o esqueleto tenha uma superficie
+/// publica verificavel antes das tasks T7-T14 — e para que qualquer consumidor
+/// (teste, DI, reflexao) tenha um <c>typeof</c> estavel para apontar ao assembly
+/// sem depender de um tipo de dominio que ainda nao existe.
+/// </summary>
+public sealed class AiKitAssemblyMarker
+{
+    private AiKitAssemblyMarker()
+    {
+    }
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/ConversationStore.cs

@@ -0,0 +1,174 @@
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Morph.AiKit.Conversation;
+
+/// <summary>
+/// O <see cref="ChatHistoryProvider"/> da casa: o historico de conversa vive no acervo
+/// <b>do projeto</b> (<see cref="IConversationStore"/>), nao dentro da
+/// <see cref="AgentSession"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>A decisao que este arquivo torna compilavel.</b> O caminho embutido do MAF
+/// (<c>InMemoryChatHistoryProvider</c>) guarda a conversa no estado da sessao, o que resolve
+/// um chat de demonstracao e nao resolve um CRM multi-tenant: a conversa precisa sobreviver
+/// ao restart, ser lida por relatorio, ser filtrada por tenant e ser apagada a pedido do
+/// titular. Aqui a <see cref="AgentSession"/> guarda apenas <b>a chave</b> da conversa; o
+/// conteudo mora onde o projeto puder consulta-lo — tipicamente uma coluna <c>jsonb</c>.
+/// </para>
+/// <para>
+/// <b>A invariante que o teste cobra:</b> o provider e <b>uma instancia compartilhada por
+/// todas as sessoes</b>. Por isso este tipo <b>nao tem campo de estado por conversa</b> — o
+/// unico estado por sessao vive em <see cref="ProviderSessionState{TState}"/>, dentro da
+/// propria <see cref="AgentSession"/>. Um campo de instancia guardando "a conversa atual"
+/// e como o historico de um usuario aparece na tela de outro, e a falha nao aparece em teste
+/// de uma sessao so: aparece em producao, sob concorrencia, como vazamento de dado alheio.
+/// </para>
+/// <para>
+/// <b>De onde vem a chave da conversa</b>, nesta ordem:
+/// <list type="number">
+/// <item>o que o projeto amarrou com <see cref="BindConversation"/> — o caso do CRM, em que
+/// a conversa ja existe como registro antes de o agente entrar;</item>
+/// <item>o <c>ConversationId</c> da sessao, quando o proprio provider de modelo gerencia a
+/// conversa (<see cref="ChatClientAgentSession"/>);</item>
+/// <item>um id novo, <see cref="Guid.CreateVersion7"/> — ordenavel no tempo, ao contrario de
+/// <c>Guid.NewGuid</c>, que fragmenta indice de banco.</item>
+/// </list>
+/// </para>
+/// </remarks>
+public sealed class ConversationStore : ChatHistoryProvider
+{
+    /// <summary>
+    /// Chave sob a qual a identidade da conversa e guardada no estado da sessao. Fixa e
+    /// publica porque ela viaja na serializacao da sessao: mudar esta string quebra a
+    /// retomada de toda conversa ja persistida.
+    /// </summary>
+    public const string ConversationIdStateKey = "morph.conversation.id";
+
+    private readonly IConversationStore _store;
+    private readonly ProviderSessionState<string> _conversationId;
+
+    /// <summary>Monta o provider sobre um acervo.</summary>
+    /// <param name="store">Onde o historico e lido e gravado. Nunca nulo.</param>
+    public ConversationStore(IConversationStore store)
+    {
+        ArgumentNullException.ThrowIfNull(store);
+
+        _store = store;
+        _conversationId = new ProviderSessionState<string>(NewConversationId, ConversationIdStateKey);
+    }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// Declara a chave que este provider ocupa no estado da sessao — e o que permite ao MAF
+    /// serializar e retomar uma sessao sem adivinhar o que e de quem.
+    /// </remarks>
+    public override IReadOnlyList<string> StateKeys => [ConversationIdStateKey];
+
+    /// <summary>
+    /// Amarra a sessao a uma conversa que <b>ja existe</b> no acervo do projeto. E o caminho
+    /// do CRM: a conversa nasce como registro de negocio, e o agente entra nela.
+    /// </summary>
+    /// <remarks>
+    /// Chamar isto depois de a sessao ja ter carregado historico troca a conversa sob os pes
+    /// da sessao. Amarre logo apos <c>CreateSessionAsync</c>.
+    /// </remarks>
+    /// <param name="session">A sessao.</param>
+    /// <param name="conversationId">A chave da conversa no acervo.</param>
+    public void BindConversation(AgentSession session, string conversationId)
+    {
+        ArgumentNullException.ThrowIfNull(session);
+        ArgumentException.ThrowIfNullOrWhiteSpace(conversationId);
+
+        _conversationId.SaveState(session, conversationId);
+    }
+
+    /// <summary>
+    /// A chave da conversa desta sessao, criando-a se ainda nao houver. Le e escreve
+    /// <b>na sessao</b>, jamais num campo deste objeto.
+    /// </summary>
+    public string GetConversationId(AgentSession session)
+    {
+        ArgumentNullException.ThrowIfNull(session);
+
+        return _conversationId.GetOrInitializeState(session);
+    }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// Devolve o historico guardado; as mensagens desta volta sao acrescentadas pelo agente
+    /// depois. Repetir aqui as mensagens do pedido duplicaria o turno corrente no prompt.
+    /// </remarks>
+    protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
+        InvokingContext context,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        return await _store
+            .LoadAsync(GetConversationId(RequireSession(context.Session)), cancellationToken)
+            .ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// <para>
+    /// Grava o pedido e a resposta <b>desta</b> volta, nessa ordem — e so eles. Regravar o
+    /// historico inteiro a cada volta faria a conversa crescer em progressao geometrica.
+    /// </para>
+    /// <para>
+    /// <b>Volta que falhou nao e gravada.</b> Com <c>InvokeException</c> preenchida nao ha
+    /// resposta; persistir o pedido sozinho deixaria a conversa terminando numa pergunta que
+    /// o modelo nunca respondeu, e a proxima volta a mandaria de novo — o usuario veria a si
+    /// mesmo repetido.
+    /// </para>
+    /// </remarks>
+    protected override async ValueTask StoreChatHistoryAsync(
+        InvokedContext context,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        if (context.InvokeException is not null)
+        {
+            return;
+        }
+
+        // Os dois lados sao anulaveis no contrato do MAF (a resposta some quando a volta
+        // falhou, e o pedido pode vir vazio numa continuacao). Tratados como ausencia, nunca
+        // desreferenciados.
+        List<ChatMessage> round =
+        [
+            .. context.RequestMessages ?? [],
+            .. context.ResponseMessages ?? [],
+        ];
+
+        if (round.Count == 0)
+        {
+            return;
+        }
+
+        await _store
+            .AppendAsync(GetConversationId(RequireSession(context.Session)), round, cancellationToken)
+            .ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// O MAF declara <c>InvokingContext.Session</c> como anulavel, e uma invocacao sem
+    /// sessao nao tem onde guardar a identidade da conversa. As duas saidas silenciosas sao
+    /// piores que a recusa: inventar um id grava uma linha orfa que ninguem consegue ler de
+    /// novo, e usar uma chave fixa junta conversas de tenants diferentes no mesmo balde —
+    /// que e o vazamento que este provider existe para impedir.
+    /// </summary>
+    private static AgentSession RequireSession(AgentSession? session)
+        => session ?? throw new InvalidOperationException(
+            "ConversationStore foi invocado sem AgentSession. Sem sessao nao ha identidade de " +
+            "conversa: crie a sessao com CreateSessionAsync e passe-a em RunAsync. Persistir " +
+            "sem chave gravaria conversa orfa ou misturaria conversas de usuarios diferentes.");
+
+    private static string NewConversationId(AgentSession? session)
+        => session is ChatClientAgentSession { ConversationId: { Length: > 0 } serviceManaged }
+            ? serviceManaged
+            : Guid.CreateVersion7().ToString("n");
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/IConversationStore.cs

@@ -0,0 +1,54 @@
+using Microsoft.Extensions.AI;
+
+namespace Morph.AiKit.Conversation;
+
+/// <summary>
+/// Onde o historico de conversa fica guardado. <b>A costura entre o kit e o banco do
+/// projeto</b> — e o unico ponto do <see cref="ConversationStore"/> que um projeto precisa
+/// implementar para trocar memoria por tabela.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>A decisao da casa que este tipo torna compilavel:</b> a conversa vive no armazenamento
+/// <b>do projeto</b>, nao dentro da <c>AgentSession</c>. Num CRM multi-tenant a conversa e
+/// um registro de negocio — ela precisa sobreviver ao restart do processo, ser lida por
+/// relatorio, ser filtrada por tenant e ser apagada a pedido do titular. Nada disso e
+/// possivel quando o historico so existe na memoria de uma sessao.
+/// </para>
+/// <para>
+/// <b>O kit nao conhece banco.</b> Esta interface e deliberadamente pequena e sem tipo de
+/// infraestrutura na assinatura: nenhum <c>DbContext</c>, nenhuma conexao, nenhum
+/// <c>jsonb</c>. A implementacao de producao vive no projeto (handler falando com o
+/// <c>ApplicationDbContext</c> direto, sem camada de service e sem repository generico);
+/// a implementacao de teste e <see cref="InMemoryConversationStore"/>.
+/// </para>
+/// <para>
+/// <b>Contrato de identidade:</b> <c>conversationId</c> e a chave do acervo, opaca para o
+/// kit. Num CRM ela costuma ser o id da linha de conversa — e por isso
+/// <see cref="ConversationStore.BindConversation"/> existe: e como o projeto amarra uma
+/// sessao a uma conversa que ja existe, em vez de deixar o kit inventar um id.
+/// </para>
+/// <para>
+/// <b>Contrato de concorrencia:</b> uma unica instancia atende todas as sessoes ao mesmo
+/// tempo. A implementacao precisa ser segura para uso concorrente e, acima de tudo,
+/// <b>nunca deixar mensagem de uma conversa aparecer em outra</b> — a chave e o unico
+/// isolamento que existe aqui.
+/// </para>
+/// </remarks>
+public interface IConversationStore
+{
+    /// <summary>
+    /// O historico da conversa, na ordem cronologica. Conversa inexistente devolve lista
+    /// <b>vazia</b>, nunca nulo e nunca excecao: uma primeira volta e o caso normal.
+    /// </summary>
+    ValueTask<IReadOnlyList<ChatMessage>> LoadAsync(string conversationId, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Acrescenta as mensagens de uma volta ao fim da conversa. Chamado uma vez por volta,
+    /// com o pedido e a resposta daquela volta — nunca com o historico inteiro.
+    /// </summary>
+    ValueTask AppendAsync(
+        string conversationId,
+        IReadOnlyList<ChatMessage> messages,
+        CancellationToken cancellationToken);
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/InMemoryConversationStore.cs

@@ -0,0 +1,75 @@
+using System.Collections.Concurrent;
+using Microsoft.Extensions.AI;
+
+namespace Morph.AiKit.Conversation;
+
+/// <summary>
+/// <see cref="IConversationStore"/> em memoria. <b>Para teste e para prototipo</b> — nao
+/// para producao: o historico morre com o processo, e um CRM que perde a conversa no deploy
+/// nao tem conversa.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Existe para que a suite do kit prove o <see cref="ConversationStore"/> <b>sem banco</b>,
+/// e para que um projeto tenha um exemplar de referencia do contrato antes de escrever a
+/// versao com <c>jsonb</c>.
+/// </para>
+/// <para>
+/// <b>Seguro sob concorrencia por construcao</b>, e nao por acidente: uma
+/// <see cref="ConcurrentDictionary{TKey, TValue}"/> por conversa, e a lista de cada conversa
+/// sempre mutada sob o lock daquela conversa. Sem isso, o teste de duas sessoes concorrentes
+/// mediria a falta de trava aqui em vez do isolamento do provider.
+/// </para>
+/// </remarks>
+public sealed class InMemoryConversationStore : IConversationStore
+{
+    private readonly ConcurrentDictionary<string, List<ChatMessage>> _conversations =
+        new(StringComparer.Ordinal);
+
+    /// <summary>As conversas que existem no acervo, para inspecao em teste.</summary>
+    public IReadOnlyCollection<string> ConversationIds => _conversations.Keys.ToArray();
+
+    /// <inheritdoc />
+    public ValueTask<IReadOnlyList<ChatMessage>> LoadAsync(
+        string conversationId,
+        CancellationToken cancellationToken)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(conversationId);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        if (!_conversations.TryGetValue(conversationId, out var messages))
+        {
+            return ValueTask.FromResult<IReadOnlyList<ChatMessage>>([]);
+        }
+
+        lock (messages)
+        {
+            return ValueTask.FromResult<IReadOnlyList<ChatMessage>>([.. messages]);
+        }
+    }
+
+    /// <inheritdoc />
+    public ValueTask AppendAsync(
+        string conversationId,
+        IReadOnlyList<ChatMessage> messages,
+        CancellationToken cancellationToken)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(conversationId);
+        ArgumentNullException.ThrowIfNull(messages);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        if (messages.Count == 0)
+        {
+            return ValueTask.CompletedTask;
+        }
+
+        var conversation = _conversations.GetOrAdd(conversationId, _ => []);
+
+        lock (conversation)
+        {
+            conversation.AddRange(messages);
+        }
+
+        return ValueTask.CompletedTask;
+    }
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Evals/CountingChatClient.cs

@@ -0,0 +1,71 @@
+using Microsoft.Extensions.AI;
+
+namespace Morph.AiKit.Evals;
+
+/// <summary>
+/// Conta quantas vezes o cliente interno foi realmente invocado, e repassa tudo o mais
+/// intacto.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que existe.</b> Nos modos que TEM cliente real (<see cref="EvalMode.Refresh"/> e
+/// <see cref="EvalMode.Online"/>) nao ha <see cref="OfflineChatClient"/> para contar, e sem
+/// contador o sumario nao consegue dizer se a arvore de cache mudou. "A cache esta fria" e
+/// uma afirmacao com consequencia (a arvore precisa ser commitada), e afirmacao com
+/// consequencia se mede.
+/// </para>
+/// <para>
+/// <b><see cref="GetService"/> repassa VERBATIM</b>, e isso e load-bearing: e por ele que o
+/// <c>ChatClientMetadata</c> — com o <c>ProviderName</c> e o <c>DefaultModelId</c> que
+/// entram na CHAVE de cache — chega a camada de cache. Um wrapper que respondesse por conta
+/// propria aqui gravaria a arvore sob uma identidade diferente da que a leitura offline
+/// replica, e todo cenario daria miss.
+/// </para>
+/// </remarks>
+public sealed class CountingChatClient(IChatClient inner) : IChatClient
+{
+    private readonly IChatClient _inner = inner ?? throw new ArgumentNullException(nameof(inner));
+    private readonly Lock _gate = new();
+    private int _calls;
+
+    /// <summary>Quantas chamadas atravessaram ate o cliente real.</summary>
+    public int Calls
+    {
+        get { lock (_gate) { return _calls; } }
+    }
+
+    /// <inheritdoc />
+    public Task<ChatResponse> GetResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        Count();
+        return _inner.GetResponseAsync(messages, options, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        Count();
+        return _inner.GetStreamingResponseAsync(messages, options, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public object? GetService(Type serviceType, object? serviceKey = null)
+        => _inner.GetService(serviceType, serviceKey);
+
+    /// <inheritdoc />
+    public void Dispose() => _inner.Dispose();
+
+    private void Count()
+    {
+        lock (_gate)
+        {
+            _calls++;
+        }
+    }
+}