@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/AgentFactoryTests.cs

@@ -0,0 +1,495 @@
+using System.Diagnostics;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Agents;
+using Morph.AiKit.Providers;
+using Morph.AiKit.Tests.Fakes;
+using Xunit;
+
+namespace Morph.AiKit.Tests;
+
+/// <summary>
+/// Canarios da <see cref="AgentFactory"/> (T10). Duas afirmacoes sao o coracao do arquivo:
+/// <b>a precedencia do protocolo</b> (spec vence o alias quando presente, alias vence quando
+/// a spec cala) e <b>a ordem do pipeline</b>, observada na sequencia real de chamadas, nao
+/// na leitura do codigo.
+/// </summary>
+/// <remarks>
+/// Todo <c>await</c> passa <c>TestContext.Current.CancellationToken</c> — exigencia do
+/// analisador xUnit1051, que sob <c>TreatWarningsAsErrors</c> e build vermelho.
+/// </remarks>
+public sealed class AgentFactoryTests
+{
+    // ---------------------------------------------------------------------------------
+    // Documentos de registry usados pelos casos
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>Um alias Responses e um alias Chat COM o limite do GPT-5.4 declarado.</summary>
+    private const string TwoProtocolsDocument = """
+    {
+      "version": "2.0",
+      "defaultAlias": "responses-alias",
+      "aliases": {
+        "responses-alias": {
+          "provider": "openai",
+          "model": "gpt-5.4",
+          "api": "responses",
+          "pricing": { "inputPerMTok": 1.25, "outputPerMTok": 10.0 }
+        },
+        "chat-alias": {
+          "provider": "openai",
+          "model": "gpt-5.4",
+          "api": "chat",
+          "pricing": { "inputPerMTok": 1.25, "outputPerMTok": 10.0 },
+          "constraints": {
+            "toolCallingRequiresReasoningEffortNone": true,
+            "provenance": "Documentacao OpenAI citada na issue #93."
+          }
+        }
+      }
+    }
+    """;
+
+    private static AgentSpec Spec(string alias = "responses-alias", AgentApi? api = null)
+        => new() { Alias = alias, Instructions = "voce e um agente de teste", Api = api };
+
+    // ---------------------------------------------------------------------------------
+    // doneCriteria 1 — a precedencia do api:
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Spec calada: vale o <c>api:</c> do alias. O seletor de cliente e o observatorio —
+    /// ele recebe o protocolo <b>efetivo</b>, ja resolvido.
+    /// </summary>
+    [Fact]
+    public void TheAliasApiWinsWhenTheSpecDeclaresNone()
+    {
+        var seen = new List<AgentApi>();
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry, new AgentFactoryOptions
+        {
+            ChatClientSelector = (_, api) => { seen.Add(api); return new FakeChatClient(); },
+        });
+
+        _ = factory.Create(Spec("responses-alias"));
+        _ = factory.Create(Spec("chat-alias"));
+
+        Assert.Equal([AgentApi.Responses, AgentApi.Chat], seen);
+    }
+
+    /// <summary>
+    /// Spec preenchida: ela vence, nos dois sentidos. A regra nao e reimplementada aqui —
+    /// a fabrica chama <see cref="AgentSpec.ResolveApi"/> (T7), e este teste morre se
+    /// alguem inverter a precedencia la ou copia-la para ca.
+    /// </summary>
+    [Fact]
+    public void TheSpecApiWinsOverTheAliasInBothDirections()
+    {
+        var seen = new List<AgentApi>();
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry, new AgentFactoryOptions
+        {
+            ChatClientSelector = (_, api) => { seen.Add(api); return new FakeChatClient(); },
+        });
+
+        _ = factory.Create(Spec("responses-alias", AgentApi.Chat));
+        _ = factory.Create(Spec("chat-alias", AgentApi.Responses));
+
+        Assert.Equal([AgentApi.Chat, AgentApi.Responses], seen);
+    }
+
+    /// <summary>
+    /// Sem seletor, "a spec vence" nao pode ser cumprido: o registry memoiza UM cliente por
+    /// alias, construido para o protocolo do alias. A fabrica recusa nomeando os dois
+    /// protocolos, em vez de devolver um agente que diz falar um e fala outro.
+    /// </summary>
+    [Fact]
+    public void WithoutASelectorADivergentSpecApiIsRefusedNamingBothProtocols()
+    {
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry);
+
+        var error = Assert.Throws<AgentFactoryException>(
+            () => factory.Create(Spec("responses-alias", AgentApi.Chat)));
+
+        Assert.Equal(AgentFactoryError.ProtocolWithoutSelector, error.Reason);
+        Assert.Contains("Chat", error.Message, StringComparison.Ordinal);
+        Assert.Contains("Responses", error.Message, StringComparison.Ordinal);
+        Assert.Contains("responses-alias", error.Message, StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    /// Sem divergencia e sem seletor, o caminho normal: o cliente memoizado do alias, uma
+    /// unica construcao por alias, por mais agentes que se criem.
+    /// </summary>
+    [Fact]
+    public void WithoutASelectorEveryAgentOfAnAliasSharesTheMemoizedClient()
+    {
+        var providerFactory = new FakeProviderClientFactory();
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, providerFactory);
+        var factory = new AgentFactory(registry);
+
+        _ = factory.Create(Spec("responses-alias"));
+        _ = factory.Create(Spec("responses-alias"));
+
+        Assert.Equal(1, providerFactory.CreateCount);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // doneCriteria 2 — a ordem do pipeline, observada nas chamadas
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// A ordem completa, medida numa invocacao com <b>duas</b> voltas de tool calling.
+    /// </summary>
+    /// <remarks>
+    /// O que a sequencia prova, e que nenhuma leitura de codigo prova: o encaixe de custo
+    /// entra e sai <b>uma</b> vez envolvendo as duas voltas (esta ACIMA do
+    /// <c>FunctionInvokingChatClient</c>), e o encaixe de telemetria entra e sai <b>duas</b>
+    /// vezes, uma por chamada ao modelo (esta ABAIXO). Trocar os dois de lugar muda esta
+    /// lista, e o teste morre.
+    /// </remarks>
+    [Fact]
+    public async Task ThePipelineOrderIsUsageCostAboveFunctionInvocationAndTelemetryBelowIt()
+    {
+        var log = new List<string>();
+        var leaf = ScriptedToolCallThenAnswer();
+
+        var agent = BuildAgentWithProbes(leaf, log, spec: Spec() with
+        {
+            Tools = [AIFunctionFactory.Create(() => "42", "answer")],
+        });
+
+        var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken);
+        var response = await agent.RunAsync(
+            "qual e a resposta?",
+            session,
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("a resposta e 42", response.Text);
+        Assert.Equal(2, leaf.CallCount);
+        Assert.Equal(
+            [
+                "usage-cost:enter",
+                "telemetry:enter",
+                "telemetry:exit",
+                "telemetry:enter",
+                "telemetry:exit",
+                "usage-cost:exit",
+            ],
+            log);
+    }
+
+    /// <summary>
+    /// A razao de o custo ficar acima do FICC, em numeros: ele ve UMA resposta com o uso
+    /// somado das duas voltas (10+30 de entrada, 4+6 de saida). Abaixo do FICC veria duas
+    /// respostas parciais — e leria um <c>UsageDetails</c> que o proprio FICC muta para
+    /// acumular, o que faria a mesma conta sair diferente conforme a hora de ler.
+    /// </summary>
+    [Fact]
+    public async Task UsageCostAboveFunctionInvocationSeesTheUsageOfEveryToolRoundSummedOnce()
+    {
+        var log = new List<string>();
+        var leaf = ScriptedToolCallThenAnswer();
+        var seenUsage = new List<UsageDetails?>();
+
+        var agent = BuildAgentWithProbes(leaf, log, spec: Spec() with
+        {
+            Tools = [AIFunctionFactory.Create(() => "42", "answer")],
+        }, onUsageCostResponse: r => seenUsage.Add(r.Usage));
+
+        var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken);
+        _ = await agent.RunAsync(
+            "qual e a resposta?",
+            session,
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        var usage = Assert.Single(seenUsage);
+        Assert.Equal(40, usage!.InputTokenCount);
+        Assert.Equal(10, usage.OutputTokenCount);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // As opcoes de nivel de agente (T7) chegam ao lugar que a T7 declarou
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// <c>MaxToolIterations</c> e <c>AllowConcurrentToolInvocation</c> tem destino nomeado
+    /// no contrato da T7. Aqui eles sao lidos <b>do objeto real</b> do pipeline, via
+    /// <c>GetService</c> — nao de um campo que a fabrica tenha guardado.
+    /// </summary>
+    [Fact]
+    public void TheAgentLevelKnobsReachTheFunctionInvokingChatClient()
+    {
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry);
+
+        var agent = factory.Create(Spec() with
+        {
+            Options = new AgentSpecOptions { MaxToolIterations = 3, AllowConcurrentToolInvocation = true },
+        });
+
+        var functionInvoking = Assert.IsType<FunctionInvokingChatClient>(
+            agent.GetService(typeof(FunctionInvokingChatClient)));
+
+        Assert.Equal(3, functionInvoking.MaximumIterationsPerRequest);
+        Assert.True(functionInvoking.AllowConcurrentInvocation);
+    }
+
+    /// <summary>
+    /// <c>TimeoutSeconds</c> vira <see cref="CancellationToken"/> de verdade: um cliente que
+    /// nunca responde e cancelado, em vez de pendurar a invocacao.
+    /// </summary>
+    [Fact]
+    public async Task TimeoutSecondsBecomesACancellationTokenThatActuallyCancels()
+    {
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry, new AgentFactoryOptions
+        {
+            ChatClientSelector = (_, _) => new NeverAnsweringChatClient(),
+        });
+
+        var agent = factory.Create(Spec() with
+        {
+            Options = new AgentSpecOptions { TimeoutSeconds = 1 },
+        });
+
+        var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken);
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(
+            () => agent.RunAsync("oi", session, cancellationToken: TestContext.Current.CancellationToken));
+    }
+
+    // ---------------------------------------------------------------------------------
+    // A spec inteira chega as ChatOptions do agente
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// O modelo vem do alias (a spec nunca cita modelo), as instrucoes e o schema vem da
+    /// spec, e <see cref="AgentSpecOptions.ApplyTo"/> nao atropela nem as tools nem o
+    /// formato de resposta ja definidos.
+    /// </summary>
+    [Fact]
+    public async Task TheSpecReachesTheChatOptionsWithoutClobberingToolsOrSchema()
+    {
+        using var schemaDocument = JsonDocument.Parse("""{"type":"object"}""");
+        var leaf = new FakeChatClient().EnqueueText("ok");
+
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry, new AgentFactoryOptions
+        {
+            ChatClientSelector = (_, _) => leaf,
+        });
+
+        var agent = factory.Create(Spec() with
+        {
+            Name = "agente-de-teste",
+            Description = "so para o teste",
+            Tools = [AIFunctionFactory.Create(() => "42", "answer")],
+            OutputSchema = schemaDocument.RootElement.Clone(),
+            Options = new AgentSpecOptions { Temperature = 0.2f, MaxOutputTokens = 128 },
+        });
+
+        var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken);
+        _ = await agent.RunAsync("oi", session, cancellationToken: TestContext.Current.CancellationToken);
+
+        var received = Assert.Single(leaf.ReceivedOptions);
+        Assert.NotNull(received);
+        Assert.Equal("voce e um agente de teste", received.Instructions);
+        Assert.Equal("gpt-5.4", received.ModelId);
+        Assert.Equal(0.2f, received.Temperature);
+        Assert.Equal(128, received.MaxOutputTokens);
+        Assert.Equal("answer", Assert.Single(received.Tools!).Name);
+        Assert.IsType<ChatResponseFormatJson>(received.ResponseFormat);
+        Assert.Equal("agente-de-teste", agent.Name);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Recusas
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Limite de alias violado nao vira agente. A recusa carrega a procedencia escrita no
+    /// registry — sem ela, o limite nao teria sequer carregado (T8).
+    /// </summary>
+    [Fact]
+    public void AViolatedAliasConstraintRefusesTheAgentAndCarriesItsProvenance()
+    {
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry);
+
+        var error = Assert.Throws<AgentFactoryException>(() => factory.Create(Spec("chat-alias") with
+        {
+            Tools = [AIFunctionFactory.Create(() => "42", "answer")],
+            Options = new AgentSpecOptions { ReasoningEffort = ReasoningEffort.High },
+        }));
+
+        Assert.Equal(AgentFactoryError.ConstraintViolated, error.Reason);
+        Assert.Contains("issue #93", error.Message, StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    /// O MESMO alias, sem tools, nao viola nada: o limite tem quatro fatos, e tres nao
+    /// bastam. O canario existe para que a recusa acima nao seja confundida com "modelo de
+    /// raciocinio rejeita tool".
+    /// </summary>
+    [Fact]
+    public void TheSameAliasWithoutToolsCreatesTheAgentNormally()
+    {
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry);
+
+        var agent = factory.Create(Spec("chat-alias") with
+        {
+            Options = new AgentSpecOptions { ReasoningEffort = ReasoningEffort.High },
+        });
+
+        Assert.NotNull(agent);
+    }
+
+    /// <summary>Alias desconhecido falha na fabrica com o mesmo erro do registry.</summary>
+    [Fact]
+    public void AnUnknownAliasFailsAtCreateTime()
+    {
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry);
+
+        var error = Assert.Throws<ModelRegistryException>(() => factory.Create(Spec("nao-existe")));
+
+        Assert.Equal(ModelRegistryError.UnknownAlias, error.Reason);
+    }
+
+    /// <summary>Seletor que devolve nulo e recusa explicita, nunca agente sem cliente.</summary>
+    [Fact]
+    public void ASelectorThatReturnsNullIsRefusedInsteadOfProducingAClientlessAgent()
+    {
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry, new AgentFactoryOptions
+        {
+            ChatClientSelector = (_, _) => null!,
+        });
+
+        var error = Assert.Throws<AgentFactoryException>(() => factory.Create(Spec()));
+
+        Assert.Equal(AgentFactoryError.NoChatClient, error.Reason);
+    }
+
+    /// <summary>
+    /// Sem nenhum encaixe preenchido, o agente e valido e responde. Um agente sem custo e
+    /// sem telemetria nao e um agente pela metade.
+    /// </summary>
+    [Fact]
+    public async Task AnAgentWithNoHooksIsStillAValidAgentThatAnswers()
+    {
+        var leaf = new FakeChatClient().EnqueueText("pronto");
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry, new AgentFactoryOptions
+        {
+            ChatClientSelector = (_, _) => leaf,
+        });
+
+        var agent = factory.Create(Spec());
+        var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken);
+        var response = await agent.RunAsync("oi", session, cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("pronto", response.Text);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Apoio dos testes
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Roteiro de duas voltas: o modelo pede a tool, a tool responde, o modelo conclui. Os
+    /// numeros de uso sao escolhidos para que a soma (40/10) seja distinguivel de qualquer
+    /// uma das parcelas.
+    /// </summary>
+    private static FakeChatClient ScriptedToolCallThenAnswer()
+        => new FakeChatClient()
+            .Enqueue(new ChatResponse(new ChatMessage(
+                ChatRole.Assistant,
+                [new FunctionCallContent("chamada-1", "answer", null)]))
+            {
+                Usage = new UsageDetails { InputTokenCount = 10, OutputTokenCount = 4, TotalTokenCount = 14 },
+            })
+            .EnqueueTextWithUsage("a resposta e 42", inputTokens: 30, outputTokens: 6);
+
+    private static Microsoft.Agents.AI.AIAgent BuildAgentWithProbes(
+        FakeChatClient leaf,
+        List<string> log,
+        AgentSpec spec,
+        Action<ChatResponse>? onUsageCostResponse = null)
+    {
+        using var registry = ModelRegistry.FromJson(TwoProtocolsDocument, new FakeProviderClientFactory());
+        var factory = new AgentFactory(registry, new AgentFactoryOptions
+        {
+            ChatClientSelector = (_, _) => leaf,
+            ConfigureUsageCost = (builder, _, _) =>
+                builder.Use(inner => new ProbeChatClient(inner, "usage-cost", log, onUsageCostResponse)),
+            ConfigureChatTelemetry = (builder, _, _) =>
+                builder.Use(inner => new ProbeChatClient(inner, "telemetry", log, onResponse: null)),
+        });
+
+        return factory.Create(spec);
+    }
+
+    /// <summary>
+    /// Marca a entrada e a saida de uma posicao do pipeline. E o unico jeito de observar a
+    /// ORDEM: ela nao esta em nenhuma propriedade, so na sequencia das chamadas.
+    /// </summary>
+    private sealed class ProbeChatClient(
+        IChatClient inner,
+        string tag,
+        List<string> log,
+        Action<ChatResponse>? onResponse) : DelegatingChatClient(inner)
+    {
+        public override async Task<ChatResponse> GetResponseAsync(
+            IEnumerable<ChatMessage> messages,
+            ChatOptions? options = null,
+            CancellationToken cancellationToken = default)
+        {
+            lock (log)
+            {
+                log.Add(tag + ":enter");
+            }
+
+            var response = await base.GetResponseAsync(messages, options, cancellationToken).ConfigureAwait(false);
+            onResponse?.Invoke(response);
+
+            lock (log)
+            {
+                log.Add(tag + ":exit");
+            }
+
+            return response;
+        }
+    }
+
+    /// <summary>Cliente que nunca responde — existe so para o timeout ter o que cancelar.</summary>
+    private sealed class NeverAnsweringChatClient : IChatClient
+    {
+        public async Task<ChatResponse> GetResponseAsync(
+            IEnumerable<ChatMessage> messages,
+            ChatOptions? options = null,
+            CancellationToken cancellationToken = default)
+        {
+            await Task.Delay(Timeout.Infinite, cancellationToken).ConfigureAwait(false);
+            throw new UnreachableException();
+        }
+
+        public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+            IEnumerable<ChatMessage> messages,
+            ChatOptions? options = null,
+            CancellationToken cancellationToken = default)
+            => throw new NotSupportedException();
+
+        public object? GetService(Type serviceType, object? serviceKey = null)
+            => serviceType == typeof(ChatClientMetadata)
+                ? new ChatClientMetadata(providerName: "never")
+                : null;
+
+        public void Dispose()
+        {
+        }
+    }
+}