@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,261 @@
+using System.Diagnostics;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Agents;
+using Morph.AiKit.Observability;
+using Morph.AiKit.Providers;
+using Morph.AiKit.Tests.Fakes;
+using Xunit;
+
+namespace Morph.AiKit.Tests;
+
+/// <summary>
+/// Canarios da telemetria (T12). O arquivo inteiro mede <b>spans</b>, com
+/// <see cref="ActivityListener"/> — nao propriedades de configuracao. Um guard contra span
+/// duplicado so pode ser provado contando spans.
+/// </summary>
+/// <remarks>
+/// Cada caso usa um <c>SourceName</c> unico, para que um teste nunca conte o span do outro.
+/// </remarks>
+public sealed class TelemetryTests
+{
+    private const string Document = """
+    {
+      "version": "2.0",
+      "defaultAlias": "text",
+      "aliases": {
+        "text": {
+          "provider": "openai",
+          "model": "gpt-5.4-mini",
+          "pricing": { "inputPerMTok": 0.25, "outputPerMTok": 2.0 }
+        }
+      }
+    }
+    """;
+
+    private static AgentSpec Spec(AgentSpecOptions? options = null)
+        => new()
+        {
+            Alias = "text",
+            Instructions = "voce e um agente de teste",
+            Name = "agente-instrumentado",
+            Options = options ?? new AgentSpecOptions(),
+        };
+
+    // ---------------------------------------------------------------------------------
+    // O caso normal: um span de agente, um span de chat
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// A forma que as GenAI conventions descrevem: <c>invoke_agent</c> como raiz e
+    /// <c>chat</c> como filho. Este teste tambem e a prova de que a escolha da T10 de montar
+    /// o proprio pipeline nao custou o span de chat — ele so existe porque a T12 o coloca.
+    /// </summary>
+    [Fact]
+    public async Task AnInstrumentedAgentEmitsOneInvokeAgentSpanAndOneChatSpan()
+    {
+        var source = NewSourceName();
+
+        var spans = await CollectAsync(source, () => BuildAgent(
+            new MorphTelemetryOptions { SourceName = source },
+            leaf: new FakeChatClient().EnqueueText("pronto")));
+
+        Assert.Equal(1, CountOf(spans, "invoke_agent"));
+        Assert.Equal(1, CountOf(spans, "chat"));
+        Assert.Null(Single(spans, "invoke_agent").Parent);
+        Assert.NotNull(Single(spans, "chat").Parent);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // O guard — as duas metades da mesma afirmacao
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// <b>O guard, no default.</b> Um pipeline que ja carrega instrumentacao (o caso real:
+    /// um <c>IChatClient</c> que veio do DI ja instrumentado) continua com UM span de chat.
+    /// </summary>
+    [Fact]
+    public async Task TheDefaultDoesNotAddASecondChatSpanOverAnAlreadyInstrumentedPipeline()
+    {
+        var source = NewSourceName();
+
+        var spans = await CollectAsync(source, () => BuildAgent(
+            new MorphTelemetryOptions { SourceName = source },
+            leaf: AlreadyInstrumented(source)));
+
+        Assert.Equal(1, CountOf(spans, "invoke_agent"));
+        Assert.Equal(1, CountOf(spans, "chat"));
+    }
+
+    /// <summary>
+    /// <b>O guard, desligado.</b> Forcar <c>InstrumentChatClient = true</c> sobre o MESMO
+    /// pipeline ja instrumentado produz o par duplicado. E o canario que documenta o risco:
+    /// sem o ramo automatico, este e o resultado.
+    /// </summary>
+    [Fact]
+    public async Task ForcingInstrumentChatClientProducesTheDuplicateChatSpan()
+    {
+        var source = NewSourceName();
+
+        var spans = await CollectAsync(source, () => BuildAgent(
+            new MorphTelemetryOptions { SourceName = source, InstrumentChatClient = true },
+            leaf: AlreadyInstrumented(source)));
+
+        Assert.Equal(1, CountOf(spans, "invoke_agent"));
+        Assert.Equal(2, CountOf(spans, "chat"));
+    }
+
+    /// <summary>
+    /// O mesmo guard no nivel do agente: aplicar a telemetria duas vezes no
+    /// <see cref="AIAgentBuilder"/> nao produz dois <c>invoke_agent</c>.
+    /// </summary>
+    [Fact]
+    public async Task TheAgentGuardKeepsASingleInvokeAgentSpanWhenTelemetryIsAppliedTwice()
+    {
+        var source = NewSourceName();
+        var telemetry = new MorphTelemetryOptions { SourceName = source };
+
+        var spans = await CollectAsync(source, () =>
+        {
+            var agent = BuildAgent(telemetry, new FakeChatClient().EnqueueText("pronto"));
+            return agent.AsBuilder().UseMorphTelemetry(telemetry).Build();
+        });
+
+        Assert.Equal(1, CountOf(spans, "invoke_agent"));
+    }
+
+    /// <summary>
+    /// <c>false</c> nao e o mesmo que o default. Com a <c>AgentFactory</c> — que monta o
+    /// proprio pipeline — desligar a instrumentacao de chat deixa a invocacao com o span do
+    /// agente e <b>nenhum</b> span de chat. O teste existe para que essa consequencia seja
+    /// um fato escrito, e nao uma surpresa em producao.
+    /// </summary>
+    [Fact]
+    public async Task TurningTheChatInstrumentationOffLeavesTheAgentSpanAndNoChatSpan()
+    {
+        var source = NewSourceName();
+
+        var spans = await CollectAsync(source, () => BuildAgent(
+            new MorphTelemetryOptions { SourceName = source, InstrumentChatClient = false },
+            leaf: new FakeChatClient().EnqueueText("pronto")));
+
+        Assert.Equal(1, CountOf(spans, "invoke_agent"));
+        Assert.Equal(0, CountOf(spans, "chat"));
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Dado sensivel
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Conteudo sensivel nasce desligado nos dois niveis — o standard exige <c>false</c>
+    /// fora de dev/staging, porque prompt e resposta sao PII do cliente.
+    /// </summary>
+    [Fact]
+    public void SensitiveDataIsOffByDefaultAtBothLevels()
+    {
+        var agent = BuildAgent(
+            new MorphTelemetryOptions { SourceName = NewSourceName() },
+            new FakeChatClient());
+
+        Assert.False(Assert.IsType<OpenTelemetryAgent>(agent).EnableSensitiveData);
+        Assert.False(Assert.IsType<OpenTelemetryChatClient>(
+            agent.GetService(typeof(OpenTelemetryChatClient))).EnableSensitiveData);
+    }
+
+    /// <summary>
+    /// A spec pode ligar o dado sensivel para UM agente sem mexer na configuracao global —
+    /// e o destino que a T7 declarou para <c>EnableSensitiveTelemetry</c>. Nulo na spec
+    /// ("nao opinei") preserva o valor global; preenchido, vence.
+    /// </summary>
+    [Fact]
+    public void TheSpecCanOverrideSensitiveDataForASingleAgent()
+    {
+        var telemetry = new MorphTelemetryOptions { SourceName = NewSourceName() };
+
+        var loud = BuildAgent(
+            telemetry,
+            new FakeChatClient(),
+            spec: Spec(new AgentSpecOptions { EnableSensitiveTelemetry = true }));
+
+        Assert.True(Assert.IsType<OpenTelemetryAgent>(loud).EnableSensitiveData);
+        Assert.True(Assert.IsType<OpenTelemetryChatClient>(
+            loud.GetService(typeof(OpenTelemetryChatClient))).EnableSensitiveData);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Configuracao invalida
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Source em branco e recusado na construcao: um <c>ActivitySource</c> sem nome nao pode
+    /// ser registrado em <c>AddSource(...)</c>, e a telemetria sumiria em silencio.
+    /// </summary>
+    [Fact]
+    public void ABlankSourceNameIsRefusedAtConstruction()
+        => Assert.Throws<ArgumentException>(() => new MorphTelemetryOptions { SourceName = "   " });
+
+    // ---------------------------------------------------------------------------------
+    // Apoio dos testes
+    // ---------------------------------------------------------------------------------
+
+    private static string NewSourceName() => "morph.aikit.test." + Guid.CreateVersion7().ToString("N");
+
+    /// <summary>Um pipeline que ja chega instrumentado — o caso real do cliente vindo do DI.</summary>
+    private static IChatClient AlreadyInstrumented(string sourceName)
+        => new FakeChatClient()
+            .EnqueueText("pronto")
+            .AsBuilder()
+            .UseOpenTelemetry(sourceName: sourceName)
+            .Build();
+
+    private static AIAgent BuildAgent(MorphTelemetryOptions telemetry, IChatClient leaf, AgentSpec? spec = null)
+    {
+        using var registry = ModelRegistry.FromJson(Document, new FakeProviderClientFactory());
+        var factory = new AgentFactory(
+            registry,
+            new AgentFactoryOptions { ChatClientSelector = (_, _) => leaf }.WithMorphTelemetry(telemetry));
+
+        return factory.Create(spec ?? Spec());
+    }
+
+    /// <summary>
+    /// Coleta os spans de UMA invocacao. O listener e registrado antes de o agente existir e
+    /// removido no fim — telemetria e estado global do processo, e um listener vazado
+    /// contaminaria os outros casos.
+    /// </summary>
+    private static async Task<IReadOnlyList<Activity>> CollectAsync(string sourceName, Func<AIAgent> build)
+    {
+        var spans = new List<Activity>();
+
+        using var listener = new ActivityListener
+        {
+            ShouldListenTo = candidate => candidate.Name == sourceName,
+            Sample = (ref ActivityCreationOptions<ActivityContext> _) => ActivitySamplingResult.AllDataAndRecorded,
+            ActivityStopped = activity =>
+            {
+                lock (spans)
+                {
+                    spans.Add(activity);
+                }
+            },
+        };
+
+        ActivitySource.AddActivityListener(listener);
+
+        var agent = build();
+        var session = await agent.CreateSessionAsync(TestContext.Current.CancellationToken);
+        _ = await agent.RunAsync("oi", session, cancellationToken: TestContext.Current.CancellationToken);
+
+        lock (spans)
+        {
+            return [.. spans];
+        }
+    }
+
+    private static int CountOf(IReadOnlyList<Activity> spans, string operation)
+        => spans.Count(span => Equals(span.GetTagItem("gen_ai.operation.name"), operation));
+
+    private static Activity Single(IReadOnlyList<Activity> spans, string operation)
+        => spans.Single(span => Equals(span.GetTagItem("gen_ai.operation.name"), operation));
+}

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

@@ -0,0 +1,374 @@
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Agents;
+using Morph.AiKit.Middleware;
+using Morph.AiKit.Providers;
+using Morph.AiKit.Tests.Fakes;
+using Xunit;
+
+namespace Morph.AiKit.Tests;
+
+/// <summary>
+/// Canarios do <see cref="UsageCostMiddleware"/> (T11). A afirmacao central da task e uma
+/// so: <b><c>cost_usd</c> nao sai nulo, e o zero nunca e ambiguo</b> — ou e medicao, ou e
+/// dispensa escrita, ou e lacuna declarada.
+/// </summary>
+public sealed class UsageCostMiddlewareTests
+{
+    private static readonly DateTimeOffset FixedNow = new(2026, 9, 8, 12, 0, 0, TimeSpan.Zero);
+
+    /// <summary>Tarifa ilustrativa com desconto de cache — a que exercita a aritmetica inteira.</summary>
+    private static ModelPricing Tariff()
+        => new(InputPerMTok: 1.25m, OutputPerMTok: 10.0m, CachedInputPerMTok: 0.125m);
+
+    private static ModelAlias PricedAlias(ModelPricing? pricing = null)
+        => new("openai", "gpt-5.4", AgentApi.Responses, pricing ?? Tariff(), Endpoint: null)
+        {
+            Name = "text-heavy",
+        };
+
+    private static ModelAlias WaivedAlias()
+        => new("ollama", "qwen3:8b", AgentApi.Responses, Pricing: null, Endpoint: "http://localhost:11434")
+        {
+            Name = "local-dev",
+            PricingWaiver = "modelo local: a conta e a maquina, nao o token.",
+        };
+
+    private static (IChatClient Client, FakeChatClient Inner, FakeUsageCostSink Sink) Pipeline(
+        ModelAlias alias,
+        Action<FakeChatClient> script)
+    {
+        var inner = new FakeChatClient();
+        script(inner);
+
+        var sink = new FakeUsageCostSink();
+
+        // A extensao publica e o caminho de registro: se ela quebrar, o teste quebra junto.
+        var client = inner.AsBuilder().UseUsageCost(alias, sink, new FakeClock(FixedNow)).Build();
+
+        return (client, inner, sink);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // doneCriteria 1: Usage conhecido + ModelPricing conhecido => CostUsd EXATO
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// O valor esperado esta escrito a mao, com a semantica correta de token cacheado:
+    /// <b>cacheado e SUBCONJUNTO da entrada</b>. 1000 de entrada com 400 servidos do cache
+    /// custam 600 na tarifa cheia mais 400 na de cache — nunca 1000 mais 400. E por isso que
+    /// este caso, e nao um sem cache, e o que denuncia uma segunda aritmetica.
+    /// </summary>
+    [Fact]
+    public async Task AKnownUsageAgainstAKnownTariffProducesTheExactCostInUsd()
+    {
+        var (client, _, sink) = Pipeline(
+            PricedAlias(),
+            fake => fake.EnqueueTextWithUsage("ok", inputTokens: 1000, outputTokens: 200, cachedInputTokens: 400));
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        var record = Assert.Single(sink.Records);
+
+        // (600 * 1.25) + (400 * 0.125) + (200 * 10.0) = 750 + 50 + 2000 = 2800 por 1M tokens.
+        Assert.Equal(0.0028m, record.CostUsd);
+        Assert.Equal(UsageCostStatus.Computed, record.Status);
+        Assert.True(record.IsMeasuredCost);
+        Assert.Equal("text-heavy", record.Alias);
+        Assert.Equal(1000, record.InputTokens);
+        Assert.Equal(200, record.OutputTokens);
+        Assert.Equal(400, record.CachedInputTokens);
+        Assert.Null(record.PricingWaiver);
+        Assert.Equal(FixedNow, record.At);
+    }
+
+    /// <summary>
+    /// O canario que torna "nao existe uma segunda conta do custo" verificavel em vez de
+    /// prometido: o custo publicado tem de ser <b>identico</b> ao de
+    /// <see cref="ModelPricing.ComputeCostUsd"/> — inclusive nos casos que separam as duas
+    /// formulas plausiveis (cacheado sem tarifa de cache, cacheado igual a entrada, saida
+    /// zerada).
+    /// </summary>
+    [Theory]
+    [InlineData(1000, 200, 400L)]
+    [InlineData(1000, 200, null)]
+    [InlineData(1000, 200, 1000L)]
+    [InlineData(1000, 200, 0L)]
+    [InlineData(7, 3, 2L)]
+    [InlineData(1_000_000, 0, 999_999L)]
+    public async Task ThePublishedCostIsTheOneComputeCostUsdWouldGive(long input, long output, long? cached)
+    {
+        var pricing = Tariff();
+        var (client, _, sink) = Pipeline(
+            PricedAlias(pricing),
+            fake => fake.EnqueueTextWithUsage("ok", input, output, cached));
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(pricing.ComputeCostUsd(input, output, cached), sink.Records[0].CostUsd);
+    }
+
+    /// <summary>
+    /// Tarifa sem desconto de cache declarado: nulo em <c>CachedInputPerMTok</c> significa
+    /// "sem desconto", <b>nunca</b> "de graca" — a entrada inteira e cobrada cheia mesmo com
+    /// tokens vindos do cache.
+    /// </summary>
+    [Fact]
+    public async Task WithoutADeclaredCacheTariffTheWholeInputIsChargedAsInput()
+    {
+        var (client, _, sink) = Pipeline(
+            PricedAlias(new ModelPricing(1.25m, 10.0m, CachedInputPerMTok: null)),
+            fake => fake.EnqueueTextWithUsage("ok", inputTokens: 1000, outputTokens: 200, cachedInputTokens: 400));
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        // (1000 * 1.25) + (200 * 10.0) = 3250 por 1M tokens. O cacheado nao rende desconto.
+        Assert.Equal(0.00325m, sink.Records[0].CostUsd);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // doneCriteria 2: alias sem Pricing => CostUsd == 0, ausencia sinalizada, SEM excecao
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Alias sem tarifa e caminho previsto, nao erro. E o zero nao e anonimo: o motivo
+    /// escrito no <c>pricingWaiver</c> do registry viaja no record. Nao ha excecao — e nao
+    /// ha nulo em <c>CostUsd</c>.
+    /// </summary>
+    [Fact]
+    public async Task AnAliasWithoutATariffRecordsTokensWithZeroCostAndSaysWhy()
+    {
+        var alias = WaivedAlias();
+        var (client, _, sink) = Pipeline(
+            alias,
+            fake => fake.EnqueueTextWithUsage("ok", inputTokens: 900, outputTokens: 100));
+
+        var response = await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("ok", response.Text);
+
+        var record = Assert.Single(sink.Records);
+
+        Assert.Equal(0m, record.CostUsd);                       // zero, jamais nulo
+        Assert.Equal(UsageCostStatus.Waived, record.Status);
+        Assert.False(record.IsMeasuredCost);                    // logo, nao entra na soma
+        Assert.Equal(alias.PricingWaiver, record.PricingWaiver);
+        Assert.Equal(900, record.InputTokens);                  // os tokens continuam medidos
+        Assert.Equal(100, record.OutputTokens);
+    }
+
+    /// <summary>
+    /// A regra que sustenta a anterior mora no registry (T8): um alias sem tarifa <b>e</b>
+    /// sem dispensa nao carrega. Por isso um record <c>Waived</c> sempre tem motivo — a
+    /// ausencia por esquecimento morre antes de chegar ao middleware.
+    /// </summary>
+    [Fact]
+    public void AWaivedRecordAlwaysHasAReasonBecauseTheRegistryRefusesAnAliasWithNeither()
+    {
+        var orphan = new ModelAlias("openai", "gpt-5.4", AgentApi.Responses, Pricing: null, Endpoint: null)
+        {
+            Name = "sem-decisao",
+        };
+
+        var refusal = Assert.Throws<ModelRegistryException>(() => ModelAlias.ValidatePricingDecision(orphan));
+        Assert.Contains("sem-decisao", refusal.Message, StringComparison.Ordinal);
+
+        ModelAlias.ValidatePricingDecision(WaivedAlias());   // com dispensa escrita, passa
+    }
+
+    /// <summary>
+    /// A soma so junta o que foi medido. Uma volta tarifada mais uma dispensada somam o
+    /// custo da primeira — o zero da dispensa nao "abaixa a media" nem some do relatorio.
+    /// </summary>
+    [Fact]
+    public async Task OnlyMeasuredCostsEnterTheSum()
+    {
+        var sink = new FakeUsageCostSink();
+        var clock = new FakeClock(FixedNow);
+
+        using var paid = new FakeChatClient().EnqueueTextWithUsage("a", 1000, 200, 400);
+        using var free = new FakeChatClient().EnqueueTextWithUsage("b", 900, 100);
+
+        var paidClient = paid.AsBuilder().UseUsageCost(PricedAlias(), sink, clock).Build();
+        var freeClient = free.AsBuilder().UseUsageCost(WaivedAlias(), sink, clock).Build();
+
+        await paidClient.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "1")],
+            cancellationToken: TestContext.Current.CancellationToken);
+        await freeClient.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "2")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(2, sink.Count);
+        Assert.Equal(0.0028m, sink.MeasuredTotalUsd);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // O terceiro zero: o provider nao reportou uso
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Resposta sem <c>Usage</c>: a linha sai marcada como lacuna. Nao publicar nada faria o
+    /// custo desaparecer do relatorio, que e a mesma dor por outro angulo; publicar como
+    /// <c>Computed</c> mentiria que a volta custou zero.
+    /// </summary>
+    [Fact]
+    public async Task AResponseWithoutUsageIsRecordedAsAGapNotAsFree()
+    {
+        var (client, _, sink) = Pipeline(PricedAlias(), fake => fake.EnqueueText("sem contador"));
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        var record = Assert.Single(sink.Records);
+
+        Assert.Equal(UsageCostStatus.UsageMissing, record.Status);
+        Assert.Equal(0m, record.CostUsd);
+        Assert.False(record.IsMeasuredCost);
+        Assert.Equal(0m, sink.MeasuredTotalUsd);
+    }
+
+    /// <summary>
+    /// <c>cached &gt; input</c> e o provider se contradizendo. A conta do T8 recusa esse par
+    /// com excecao — e recusar aqui derrubaria a resposta do usuario por causa de um
+    /// contador. O middleware degrada para lacuna declarada, sem lancar.
+    /// </summary>
+    [Fact]
+    public async Task InconsistentTokenCountsBecomeADeclaredGapInsteadOfAThrownRequest()
+    {
+        var pricing = Tariff();
+        Assert.Throws<ArgumentException>(() => pricing.ComputeCostUsd(10, 5, cachedInputTokens: 11));
+
+        var (client, _, sink) = Pipeline(
+            PricedAlias(pricing),
+            fake => fake.EnqueueTextWithUsage("ok", inputTokens: 10, outputTokens: 5, cachedInputTokens: 11));
+
+        var response = await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("ok", response.Text);
+        Assert.Equal(UsageCostStatus.UsageMissing, Assert.Single(sink.Records).Status);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Uma linha por volta ao modelo — inclusive no streaming
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Duas <b>chamadas</b> a <c>GetResponseAsync</c> publicam <b>duas</b> linhas: uma por
+    /// ida ao modelo, cada uma com o seu proprio numero.
+    /// </summary>
+    /// <remarks>
+    /// O que este teste prova, e so isto: <b>uma linha por chamada</b>, sem acumulo de
+    /// estado entre chamadas. Ele NAO prova nada sobre a posicao do middleware no pipeline
+    /// — sao duas chamadas separadas, nao uma chamada com volta de tool, e aqui o
+    /// middleware e montado sozinho, sem <c>FunctionInvokingChatClient</c> nenhum. A
+    /// posicao real e o oposto do que uma leitura apressada deste teste sugeriria: o
+    /// middleware fica <b>ACIMA</b> da invocacao de funcoes, e quem prova isso e
+    /// <c>AgentFactoryTests.ThePipelineOrderIsUsageCostAboveFunctionInvocationAndTelemetryBelowIt</c>
+    /// (com <c>...SeesTheUsageOfEveryToolRoundSummedOnce</c> mostrando o uso ja somado das
+    /// duas voltas). Acima do FICC, uma conversa com tool call e <b>uma</b> chamada com o
+    /// uso ja totalizado — nao duas.
+    /// </remarks>
+    [Fact]
+    public async Task EveryTripToTheModelPublishesItsOwnLine()
+    {
+        var (client, inner, sink) = Pipeline(
+            PricedAlias(),
+            fake => fake
+                .EnqueueTextWithUsage("primeira", 1000, 200, 400)
+                .EnqueueTextWithUsage("segunda", 2000, 100, null));
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "a")],
+            cancellationToken: TestContext.Current.CancellationToken);
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "b")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(2, inner.CallCount);
+        Assert.Equal(2, sink.Count);
+        Assert.Equal(0.0028m, sink.Records[0].CostUsd);
+        Assert.Equal(0.0035m, sink.Records[1].CostUsd);   // (2000*1.25 + 100*10) / 1M
+    }
+
+    /// <summary>
+    /// No streaming o uso chega como <c>UsageContent</c> avulso. A linha sai <b>uma</b> vez,
+    /// ao fim da enumeracao, com o mesmo numero do caminho nao-streaming.
+    /// </summary>
+    [Fact]
+    public async Task StreamingPublishesOneLineAtTheEndWithTheSameNumber()
+    {
+        var (client, _, sink) = Pipeline(
+            PricedAlias(),
+            fake => fake.EnqueueTextWithUsage("streamado", 1000, 200, 400));
+
+        var updates = 0;
+        await foreach (var _ in client.GetStreamingResponseAsync(
+            [new ChatMessage(ChatRole.User, "oi")],
+            cancellationToken: TestContext.Current.CancellationToken))
+        {
+            Assert.Equal(0, sink.Count);   // nada publicado no meio da enumeracao
+            updates++;
+        }
+
+        Assert.True(updates > 0);
+        Assert.Equal(0.0028m, Assert.Single(sink.Records).CostUsd);
+    }
+
+    // ---------------------------------------------------------------------------------
+    // Higiene de construcao
+    // ---------------------------------------------------------------------------------
+
+    /// <summary>Alias ou sink nulos sao defeito de composicao e falham na construcao.</summary>
+    [Fact]
+    public void TheMiddlewareRefusesToBeBuiltWithoutAnAliasOrASink()
+    {
+        using var inner = new FakeChatClient();
+
+        Assert.Throws<ArgumentNullException>(
+            () => new UsageCostMiddleware(inner, null!, new FakeUsageCostSink()));
+
+        Assert.Throws<ArgumentNullException>(
+            () => new UsageCostMiddleware(inner, PricedAlias(), null!));
+    }
+
+    /// <summary>
+    /// O instante do record vem do <see cref="TimeProvider"/> injetado, nao do relogio do
+    /// processo — sem isso o campo <c>At</c> seria intestavel (standard
+    /// <c>backend-dotnet-testing</c>).
+    /// </summary>
+    [Fact]
+    public async Task TheTimestampComesFromTheInjectedClock()
+    {
+        var clock = new FakeClock(FixedNow);
+        var sink = new FakeUsageCostSink();
+        using var inner = new FakeChatClient()
+            .EnqueueTextWithUsage("a", 10, 10)
+            .EnqueueTextWithUsage("b", 10, 10);
+
+        var client = inner.AsBuilder().UseUsageCost(PricedAlias(), sink, clock).Build();
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "1")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        clock.Advance(TimeSpan.FromMinutes(5));
+
+        await client.GetResponseAsync(
+            [new ChatMessage(ChatRole.User, "2")],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(FixedNow, sink.Records[0].At);
+        Assert.Equal(FixedNow.AddMinutes(5), sink.Records[1].At);
+    }
+}

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/eval-cache/.morph-eval-cache.json

@@ -0,0 +1,12 @@
+{
+  "pinnedAt": "2026-09-08",
+  "packages": {
+    "Microsoft.Extensions.AI": "10.9.0",
+    "Microsoft.Extensions.AI.Evaluation": "10.9.0",
+    "Microsoft.Extensions.AI.Evaluation.Quality": "10.9.0",
+    "Microsoft.Extensions.AI.Evaluation.Reporting": "10.9.0"
+  },
+  "provider": "morph-fake",
+  "model": "morph-kit-exemplar",
+  "writtenBy": "morph-eval-fixture"
+}

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/eval-cache/cache/orcamento.acme.a-resposta-estruturada/1/CF70A7CE27BBD66A/contents.data

@@ -0,0 +1,13 @@
+{
+  "messages": [
+    {
+      "role": "assistant",
+      "contents": [
+        {
+          "$type": "text",
+          "text": "{\"valor\":\"R$ 1.200,00\",\"prazo\":\"5 dias uteis\"}"
+        }
+      ]
+    }
+  ]
+}

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/eval-cache/cache/orcamento.acme.a-resposta-estruturada/1/CF70A7CE27BBD66A/entry.json

@@ -0,0 +1,7 @@
+{
+  "scenarioName": "orcamento.acme.a-resposta-estruturada",
+  "iterationName": "1",
+  "key": "CF70A7CE27BBD66AC1E097FB07773A83302651F432FAC98DA349B93B2AC2204DB504344EF1C220390AE6504FFA3BCB81",
+  "creation": "2026-09-09T04:54:34.7288625+00:00",
+  "expiration": "2036-09-06T04:54:34.7288625+00:00"
+}