@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/templates/dotnet/ai-kit/NuGet.config

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  <clear /> e o ponto deste arquivo: sem ele o restore herda os feeds da maquina
+  (ou do runner) e "compila aqui, quebra no CI" volta a ser possivel. O kit
+  restaura de nuget.org e de mais nada.
+-->
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
+  </packageSources>
+</configuration>

package/framework/templates/dotnet/ai-kit/README.md

@@ -0,0 +1,128 @@
+# Morph.AiKit
+
+Solução .NET **compilável** que prova os standards `ai-agents/**` contra
+`framework/ai-pin.json`. Não é fragmento de referência: a unidade de consumo é o
+diretório inteiro, e é por isso que ela está registrada no `REGISTRY.json` como
+`kind: "project"` (uma entrada, `path: "dotnet/ai-kit/"`).
+
+```
+ai-kit/
+├── global.json               # GERADO do pin — banda de SDK + runner de teste
+├── Directory.Packages.props  # GERADO do pin — Central Package Management
+├── Directory.Build.props     # TFM, Nullable, TreatWarningsAsErrors
+├── NuGet.config              # <clear/> + nuget.org: restore não herda feed de máquina
+├── Morph.AiKit.sln
+├── src/Morph.AiKit/          # a biblioteca
+└── tests/Morph.AiKit.Tests/  # xUnit v3, sem rede e sem chave de API
+```
+
+## Build e teste
+
+```bash
+cd framework/templates/dotnet/ai-kit
+dotnet restore Morph.AiKit.sln
+dotnet build   Morph.AiKit.sln -c Release --no-restore
+dotnet test  --solution Morph.AiKit.sln -c Release --no-build
+```
+
+> **Nenhuma flag da era VSTest no `dotnet test` — `--nologo` mata a sessão.**
+> O `global.json` coloca este kit no **modo MTP** do `dotnet test` (SDK .NET 10).
+> Nesse modo o CLI não conhece `--nologo` e o repassa **literalmente** para o
+> aplicativo de teste, que responde `error: unknown option: --nologo`: a sessão
+> morre com o código de saída **5** e o relatório diz *"Zero testes executados"*
+> — com os 115 testes passando por baixo. Medido em 2026‑09‑08. O `dotnet build
+> --nologo` é inofensivo, e é isso que torna o erro fácil de cometer. Pela mesma
+> razão o caminho da solução vai em `--solution`, e não como argumento
+> posicional: é a grafia documentada do modo MTP (passo 5 do guia de migração).
+> `--logger`, `--collect` e `--blame` caem na mesma armadilha.
+
+> **O modo MTP muda também a SAÍDA, não só a invocação.** O sumário não é uma
+> linha: é um **bloco de 6 linhas**, o veredito **não começa** a linha
+> (`Resumo da execução de teste: Aprovado!` / `Test run summary: Passed!`) e a
+> contagem vem em linha própria, indentada, com **`total:` minúsculo** — nada
+> disso é o sumário do VSTest. Medido nos dois locales em 2026‑09‑08.
+> Consequência: **um parser escrito para o sumário do VSTest não conta os testes
+> deste projeto** — um parser que procure uma linha *começando* em
+> `Aprovado!`/`Passed!` **e** contendo `Total de testes:`/`Total:` falha nos dois
+> eixos, e nos dois locales. O conserto do parser pertence à feature
+> `verify-por-stack`; aqui isto é **registro de fronteira**, não conserto.
+
+> **Descoberta parcial não pode passar verde.** O `.csproj` de teste declara
+> `TestingPlatformCommandLineArguments` com o piso `--minimum-expected-tests
+> 115`: qualquer execução que rode menos de 115 casos sai com o código **9**.
+> Sem ele, uma execução que descobre **1 de 115** imprime *"Aprovado!"* e sai
+> **0** — medido. O piso mora no `.csproj`, e não no passo do workflow, para
+> valer em toda invocação (CI, máquina do dev e o nó `tests` do `morph-spec
+> verify`); por isso nenhum chamador repassa a flag. Ao adicionar testes, suba o
+> piso — `test/framework/ai-kit-ci-packaging.test.js` reprova um piso que ficou
+> para trás da contagem de `[Fact]`/`[Theory]`.
+
+> **`dotnet test` precisa rodar COM O CWD DENTRO deste diretório.** O opt-in do
+> Microsoft.Testing.Platform (que `xunit.v3` 4.x usa) vive em `global.json`, e o
+> SDK procura o `global.json` a partir do diretório corrente subindo — não a
+> partir do `.sln` passado no argumento. Invocado da raiz do repositório,
+> `dotnet test framework/templates/dotnet/ai-kit/Morph.AiKit.sln` falha com
+> *"Testing with VSTest target is no longer supported"*. O `dotnet build` **não**
+> tem esse problema. No CI, use `working-directory:`.
+
+## Versões de pacote
+
+**Nenhum `.csproj` declara `Version`.** Central Package Management está ligado, e
+todas as versões vivem em `Directory.Packages.props`, gerado por
+`scripts/generate-ai-pin-props.js` a partir de `framework/ai-pin.json`. Para
+mudar uma versão, mude o pin e rode `npm run generate`; `npm run generate:check`
+(dentro de `npm run verify`) reprova qualquer divergência. Um `PackageReference`
+sem `PackageVersion` correspondente falha o restore com **NU1010** — é isso que
+torna a divergência estruturalmente impossível, em vez de apenas detectável.
+
+`bin/` e `obj/` ficam fora do git e fora do tarball npm pelo `.gitignore` deste
+diretório. Uma regra no `.npmignore` da raiz **não** funcionaria: `package.json`
+→ `files` lista `framework/`, e o npm não deixa um ignore da raiz excluir nada
+sob um diretório de `files`.
+
+## Dois níveis de garantia: compilação × contrato de versão
+
+O pin tem **oito** pacotes; o kit **não** os prova todos da mesma forma, e a
+diferença é material — não é detalhe de empacotamento.
+
+| Pacote do pin | Garantia | O que reprova a PR |
+|---|---|---|
+| `Microsoft.Agents.AI` | **cobertura de compilação** | um rename de API: o kit tem `using` reais e o build quebra |
+| `Microsoft.Extensions.AI` | **cobertura de compilação** | idem |
+| `Microsoft.Extensions.AI.Evaluation` | **cobertura de compilação** | `Evals/EvalAssertion.cs` implementa `IEvaluator` |
+| `Microsoft.Extensions.AI.Evaluation.Quality` | **cobertura de compilação** | `Evals/EvalQualityEvaluators.cs` constrói os avaliadores estáveis |
+| `Microsoft.Extensions.AI.Evaluation.Reporting` | **cobertura de compilação** | `Evals/EvalFixture.cs` monta a `ReportingConfiguration` |
+| `OpenAI` | **contrato de versão** | só o restore: `NU1102` se a versão sumir do nuget.org |
+| `Google.GenAI` | **contrato de versão** | idem |
+| `ModelContextProtocol` | **contrato de versão** | idem |
+| `OpenAI` | **cobertura de compilação** | um rename: `Media/Providers/OpenAIImageProvider.cs` tem `using OpenAI.Images;` e usa `ImageClient`, `ImageEditOptions`, `GeneratedImageQuality` |
+| `Google.GenAI` | **cobertura de compilação** | um rename: os dois adaptadores de `Media/Providers/` têm `using Google.GenAI.Types;` e usam `GenerateVideosSource`, `GenerateVideosOperation`, `Blob` |
+| `ModelContextProtocol` | **contrato de versão** | só o restore: `NU1102` se a versão sumir do nuget.org |
+
+Sem eufemismo: para **um** deles, **um rename de API não reprova a PR**. O job
+`ai-kit` prova apenas que a versão pinada continua existindo no nuget.org — não
+que a API dela continua a mesma. Não existe um único `using ModelContextProtocol`
+em `src/` nem em `tests/`.
+
+**A linha mudou, e vale registrar por quê.** Até a chegada de
+`src/Morph.AiKit/Media/`, três dos cinco pacotes eram contrato de versão: o pin
+não inclui `Microsoft.Extensions.AI.OpenAI`, e sem essa ponte o kit não tocava
+tipo nenhum de `OpenAI` nem de `Google.GenAI`. O subsistema de mídia fechou a
+lacuna **sem** acrescentar pacote: o adaptador `IImageGenerator` sobre
+`ImageClient` está escrito à mão em `Media/Providers/OpenAIImageProvider.cs`, e o
+caminho de vídeo do Veo usa `Google.GenAI` direto — que é o único caminho com SDK
+.NET oficial, e por isso não havia ponte a esperar. Quem apontou a mudança foi o
+próprio canário: `test/framework/ai-kit-package-coverage.test.js` ficou vermelho
+nomeando os dois pacotes como entradas obsoletas de `RESTORE_ONLY`.
+
+O `PackageReference` de `ModelContextProtocol` **fica** no `.csproj` de propósito:
+sem alguém referenciando o pacote, o restore nunca o resolve, e aí some até a
+régua fraca (o `NU1102`) que existe hoje. Fechar essa última lacuna é expor uma
+superfície MCP de verdade no kit — escopo novo, decisão do dono do pin.
+
+Essa classificação não é prosa solta: `test/framework/ai-kit-package-coverage.test.js`
+exige que **todo** `PackageReference` do `Morph.AiKit.csproj` esteja ou
+exercitado por um `using` real em `src/`, ou listado como restore-only na
+constante do próprio teste. Um pacote novo que não caia em nenhum dos dois casos
+deixa o teste vermelho nomeando o pacote — a prosa acima não pode envelhecer em
+silêncio.

package/framework/templates/dotnet/ai-kit/global.json

@@ -0,0 +1,9 @@
+{
+  "sdk": {
+    "version": "10.0.100",
+    "rollForward": "latestFeature"
+  },
+  "test": {
+    "runner": "Microsoft.Testing.Platform"
+  }
+}

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

@@ -0,0 +1,65 @@
+namespace Morph.AiKit.Agents;
+
+/// <summary>
+/// Protocolo pelo qual um modelo e alcancado. E o campo <c>api:</c> por alias que a
+/// issue #92 exige: a MESMA familia de modelos e atendida por dois protocolos
+/// diferentes, e qual deles vale e decisao de configuracao — nunca folclore espalhado
+/// por condicional no meio do codigo.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="Responses"/> e <b>0 de proposito</b>: <c>default(AgentApi)</c> e a Responses
+/// API porque essa e a decisao da casa (Responses por padrao, Chat Completions como
+/// opt-in explicito por alias). Um alias que omite <c>api:</c> no
+/// <c>model-registry.v2.json</c> cai em Responses; usar Chat Completions exige escrever
+/// <c>"api": "chat"</c> — ou seja, exige alguem assumir a escolha por escrito.
+/// </para>
+/// <para>
+/// O enum descreve a escolha ENTRE OS DOIS PROTOCOLOS DA OpenAI. Provider que expoe um
+/// unico protocolo (Google, Ollama) ignora o campo, e por isso declara — ou omite,
+/// caindo em — <see cref="Responses"/>: escrever <c>chat</c> ali sugeriria uma escolha
+/// que naquele provider nao existe.
+/// </para>
+/// </remarks>
+public enum AgentApi
+{
+    /// <summary>Responses API — o padrao da casa. Valor 0, logo <c>default(AgentApi)</c>.</summary>
+    Responses = 0,
+
+    /// <summary>
+    /// Chat Completions — opt-in explicito por alias. Carrega limites que a Responses API
+    /// nao tem; ver <c>Morph.AiKit.Providers.ModelAliasConstraints</c>.
+    /// </summary>
+    Chat = 1,
+
+    /// <summary>
+    /// Images — geracao/edicao de imagem. <b>Nao e um protocolo de conversa</b>: um alias
+    /// com este <c>api</c> e recusado pela <c>AgentFactory</c>, com erro nomeado.
+    /// </summary>
+    /// <remarks>
+    /// Um registry so, um vocabulario so de alias: quem procura "qual modelo este projeto
+    /// usa" encontra o de imagem no mesmo lugar que o de chat. A alternativa era um
+    /// <c>media-registry.json</c> separado — duas verdades sobre o mesmo fato.
+    /// </remarks>
+    Images = 2,
+
+    /// <summary>
+    /// Videos — geracao de video. Mesma regra de <see cref="Images"/>: alias de midia nao
+    /// vira agente.
+    /// </summary>
+    Videos = 3,
+}
+
+/// <summary>Predicados sobre <see cref="AgentApi"/>.</summary>
+public static class AgentApiExtensions
+{
+    /// <summary>
+    /// Se o protocolo e de MIDIA (imagem ou video) e portanto nao fala conversa.
+    /// </summary>
+    /// <remarks>
+    /// Escrito uma vez, aqui, porque duas copias deste predicado sao como a
+    /// <c>AgentFactory</c> e o <c>ModelRegistry</c> passariam a discordar sobre o mesmo
+    /// alias.
+    /// </remarks>
+    public static bool IsMedia(this AgentApi api) => api is AgentApi.Images or AgentApi.Videos;
+}

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

@@ -0,0 +1,289 @@
+using System.Runtime.CompilerServices;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Providers;
+
+namespace Morph.AiKit.Agents;
+
+/// <summary>
+/// Transforma uma <see cref="AgentSpec"/> (o agente como dado) num
+/// <see cref="AIAgent"/> pronto para rodar. E o unico lugar do kit que conhece a ORDEM do
+/// pipeline.
+/// </summary>
+/// <remarks>
+/// <para><b>A ordem, de fora para dentro, e o contrato desta classe:</b></para>
+/// <code>
+/// OpenTelemetryAgent            span invoke_agent — cobre a invocacao inteira (T12)
+///  +- ChatClientAgent           UseProvidedChatClientAsIs = true: o pipeline abaixo e nosso
+///      +- timeout               TimeoutSeconds vira CancellationToken
+///      +- usage-cost            ve UMA resposta com o uso ja somado das voltas (T11)
+///      +- FunctionInvoking      MaxToolIterations / AllowConcurrentToolInvocation
+///      +- telemetria de chat    span chat, ABAIXO do FICC (T12)
+///      +- cliente do provider   memoizado pelo ModelRegistry
+/// </code>
+/// <para>
+/// Cada posicao foi <b>medida</b> contra o pin, nao herdada de folclore. Acima do FICC o
+/// middleware de custo recebe o uso agregado (10/4 + 30/6 chegam como 40/10); abaixo dele
+/// receberia uma resposta por volta, e ainda leria um <c>UsageDetails</c> que o FICC muta
+/// para acumular. A telemetria de chat fica abaixo do FICC porque o MAF 1.20.0 escreve, na
+/// documentacao do proprio slot que ele reserva, que so assim o span de chat fecha antes
+/// das tools e o <c>invoke_agent</c> vira raiz.
+/// </para>
+/// <para>
+/// <b>Por que <c>UseProvidedChatClientAsIs = true</c>:</b> com o default, o
+/// <c>ChatClientAgent</c> monta ele mesmo o FICC — e nao ha onde ajustar
+/// <c>MaximumIterationsPerRequest</c> nem onde encaixar o custo entre o FICC e o cliente.
+/// O preco medido dessa escolha e que o slot de telemetria que o MAF reservaria deixa de
+/// existir: sem a T12 ligada, um agente desta fabrica emite <c>invoke_agent</c> e
+/// <b>nenhum</b> span de chat. E por isso que a telemetria de chat e um encaixe nomeado, e
+/// nao um detalhe opcional.
+/// </para>
+/// </remarks>
+public sealed class AgentFactory
+{
+    private readonly ModelRegistry _registry;
+    private readonly AgentFactoryOptions _options;
+
+    /// <summary>Cria a fabrica sobre um registry ja carregado.</summary>
+    /// <param name="registry">Fonte unica de alias, protocolo e tarifa.</param>
+    /// <param name="options">Infraestrutura e encaixes. Nulo = nenhum encaixe preenchido.</param>
+    public AgentFactory(ModelRegistry registry, AgentFactoryOptions? options = null)
+    {
+        ArgumentNullException.ThrowIfNull(registry);
+
+        _registry = registry;
+        _options = options ?? new AgentFactoryOptions();
+    }
+
+    /// <summary>
+    /// Materializa a spec. Alias desconhecido, limite de alias violado ou troca de
+    /// protocolo sem seletor sao recusas <b>na construcao</b> — nunca um agente meio certo.
+    /// </summary>
+    /// <remarks>
+    /// Recusar aqui e falha de composicao, nao excecao como fluxo de controle: acontece uma
+    /// vez, na montagem, e seguir adiante seria seguir sem regua. Quem quiser inspecionar
+    /// antes chama <c>registry.Resolve(alias).CheckRequest(...)</c>, que e Result.
+    /// </remarks>
+    public AIAgent Create(AgentSpec spec)
+    {
+        ArgumentNullException.ThrowIfNull(spec);
+
+        var alias = _registry.Resolve(spec.Alias);
+        var api = spec.ResolveApi(alias.Api);
+
+        // Alias de MIDIA nao vira agente, e a recusa e aqui, na construcao. Sem ela, um
+        // alias de imagem passado por engano viraria um agente de chat apontando para um
+        // modelo que nao fala chat: a falha apareceria tarde, no primeiro turno, com uma
+        // mensagem do provider que nao diz o que aconteceu. E a companheira obrigatoria de
+        // AgentApi.Images/Videos existirem — enum novo sem recusa e uma armadilha nova.
+        if (alias.Api.IsMedia() || api.IsMedia())
+        {
+            throw AgentFactoryException.MediaAliasIsNotAnAgent(spec.Alias, alias.Api.IsMedia() ? alias.Api : api);
+        }
+
+        var check = alias.CheckRequest(
+            api,
+            spec.Tools.Count > 0,
+            spec.Options.ReasoningEffort,
+            spec.Options.Temperature is not null);
+
+        if (!check.IsSatisfied)
+        {
+            throw AgentFactoryException.ConstraintViolated(spec.Alias, check.Violations);
+        }
+
+        var agentOptions = new ChatClientAgentOptions
+        {
+            Id = Guid.CreateVersion7().ToString("N"),
+            Name = spec.Name,
+            Description = spec.Description,
+            ChatOptions = BuildChatOptions(spec, alias),
+            UseProvidedChatClientAsIs = true,
+        };
+
+        AIAgent agent = new ChatClientAgent(
+            BuildChatPipeline(ResolveChatClient(alias, api), spec, alias),
+            agentOptions,
+            _options.LoggerFactory,
+            _options.ServiceProvider);
+
+        return _options.ConfigureAgentTelemetry is { } configureAgent
+            ? configureAgent(agent.AsBuilder(), spec, alias).Build(_options.ServiceProvider)
+            : agent;
+    }
+
+    /// <summary>
+    /// As opcoes de requisicao do agente. <c>ModelId</c> vem do alias — a spec nunca cita
+    /// modelo. <c>Tools</c> e <c>ResponseFormat</c> entram antes de
+    /// <see cref="AgentSpecOptions.ApplyTo"/>, que por contrato nao sobrescreve o que ja
+    /// foi definido.
+    /// </summary>
+    private static ChatOptions BuildChatOptions(AgentSpec spec, ModelAlias alias)
+    {
+        var options = new ChatOptions
+        {
+            Instructions = spec.Instructions,
+            ModelId = alias.Model,
+        };
+
+        if (spec.Tools.Count > 0)
+        {
+            options.Tools = [.. spec.Tools];
+        }
+
+        if (spec.OutputSchema is { } schema)
+        {
+            options.ResponseFormat = ChatResponseFormat.ForJsonSchema(schema, spec.Name, spec.Description);
+        }
+
+        return spec.Options.ApplyTo(options);
+    }
+
+    private IChatClient ResolveChatClient(ModelAlias alias, AgentApi api)
+    {
+        if (_options.ChatClientSelector is { } selector)
+        {
+            return selector(alias, api) ?? throw AgentFactoryException.NoChatClient(alias.Name, api);
+        }
+
+        return api == alias.Api
+            ? _registry.GetChatClient(alias.Name)
+            : throw AgentFactoryException.ProtocolWithoutSelector(alias.Name, alias.Api, api);
+    }
+
+    private IChatClient BuildChatPipeline(IChatClient leaf, AgentSpec spec, ModelAlias alias)
+    {
+        var builder = leaf.AsBuilder();
+
+        if (spec.Options.TimeoutSeconds is { } seconds)
+        {
+            builder = builder.Use(inner => new TimeoutChatClient(inner, TimeSpan.FromSeconds(seconds)));
+        }
+
+        if (_options.ConfigureUsageCost is { } configureUsageCost)
+        {
+            builder = configureUsageCost(builder, spec, alias);
+        }
+
+        builder = builder.UseFunctionInvocation(_options.LoggerFactory, functionInvoking =>
+        {
+            if (spec.Options.MaxToolIterations is { } maxIterations)
+            {
+                functionInvoking.MaximumIterationsPerRequest = maxIterations;
+            }
+
+            if (spec.Options.AllowConcurrentToolInvocation is { } allowConcurrent)
+            {
+                functionInvoking.AllowConcurrentInvocation = allowConcurrent;
+            }
+        });
+
+        if (_options.ConfigureChatTelemetry is { } configureChatTelemetry)
+        {
+            builder = configureChatTelemetry(builder, spec, alias);
+        }
+
+        return builder.Build(_options.ServiceProvider);
+    }
+
+    /// <summary>
+    /// Realiza <see cref="AgentSpecOptions.TimeoutSeconds"/>. Vive aqui, privado, porque e
+    /// a traducao de UMA opcao para o <see cref="CancellationToken"/> que o pipeline ja
+    /// carrega — e nao um conceito que alguem deva compor por fora.
+    /// </summary>
+    private sealed class TimeoutChatClient(IChatClient inner, TimeSpan timeout) : DelegatingChatClient(inner)
+    {
+        public override async Task<ChatResponse> GetResponseAsync(
+            IEnumerable<ChatMessage> messages,
+            ChatOptions? options = null,
+            CancellationToken cancellationToken = default)
+        {
+            using var timed = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+            timed.CancelAfter(timeout);
+
+            return await base.GetResponseAsync(messages, options, timed.Token).ConfigureAwait(false);
+        }
+
+        public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+            IEnumerable<ChatMessage> messages,
+            ChatOptions? options = null,
+            [EnumeratorCancellation] CancellationToken cancellationToken = default)
+        {
+            using var timed = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+            timed.CancelAfter(timeout);
+
+            await foreach (var update in base
+                .GetStreamingResponseAsync(messages, options, timed.Token)
+                .ConfigureAwait(false))
+            {
+                yield return update;
+            }
+        }
+    }
+}
+
+/// <summary>Motivo de uma recusa da <see cref="AgentFactory"/>.</summary>
+public enum AgentFactoryError
+{
+    /// <summary>A requisicao viola um limite declarado no alias, com procedencia.</summary>
+    ConstraintViolated = 0,
+
+    /// <summary>A spec pede um protocolo diferente do alias e nao ha seletor de cliente.</summary>
+    ProtocolWithoutSelector = 1,
+
+    /// <summary>O seletor de cliente devolveu nulo.</summary>
+    NoChatClient = 2,
+
+    /// <summary>O alias e de midia (<c>api: images</c> ou <c>api: videos</c>) e nao fala conversa.</summary>
+    MediaAliasIsNotAnAgent = 3,
+}
+
+/// <summary>
+/// Recusa de composicao da <see cref="AgentFactory"/>. <c>sealed</c> e discriminada por
+/// <see cref="Reason"/>: quem trata precisa do motivo, nao de herdar do tipo.
+/// </summary>
+public sealed class AgentFactoryException : InvalidOperationException
+{
+    private AgentFactoryException(AgentFactoryError reason, string message)
+        : base(message)
+        => Reason = reason;
+
+    /// <summary>Por que a fabrica recusou.</summary>
+    public AgentFactoryError Reason { get; }
+
+    /// <summary>A requisicao viola limites do alias. A mensagem traz cada violacao com sua procedencia.</summary>
+    public static AgentFactoryException ConstraintViolated(string alias, IReadOnlyList<string> violations)
+        => new(
+            AgentFactoryError.ConstraintViolated,
+            $"alias '{alias}': a spec viola limite(s) declarado(s) do alias e o agente NAO foi criado. " +
+            string.Join(" | ", violations));
+
+    /// <summary>Divergencia de protocolo sem seletor que saiba construir o outro cliente.</summary>
+    public static AgentFactoryException ProtocolWithoutSelector(string alias, AgentApi aliasApi, AgentApi specApi)
+        => new(
+            AgentFactoryError.ProtocolWithoutSelector,
+            $"alias '{alias}': a spec pede o protocolo '{specApi}' e o alias foi construido para " +
+            $"'{aliasApi}'. O ModelRegistry memoiza UM cliente por alias, entao devolver o cliente " +
+            "memoizado seria entregar um agente que diz falar um protocolo e fala outro. Declare um " +
+            "alias com o api pedido no model-registry.v2.json, ou preencha " +
+            $"{nameof(AgentFactoryOptions)}.{nameof(AgentFactoryOptions.ChatClientSelector)}.");
+
+    /// <summary>
+    /// O alias e de midia. Recusa nomeada, na construcao — nunca um agente que aponta para
+    /// um modelo que nao fala chat.
+    /// </summary>
+    public static AgentFactoryException MediaAliasIsNotAnAgent(string alias, AgentApi api)
+        => new(
+            AgentFactoryError.MediaAliasIsNotAnAgent,
+            $"alias '{alias}': api '{api}' e um protocolo de MIDIA, nao de conversa, e um agente NAO foi " +
+            "criado. Geracao de midia nao passa por AIAgent: o ponto de entrada e " +
+            $"{nameof(Morph.AiKit.Media.IMediaGenerator)}.{nameof(Morph.AiKit.Media.IMediaGenerator.EnqueueAsync)}, " +
+            "que devolve um id de job e nunca bytes. Ver ai-agents/media-pipeline.md.");
+
+    /// <summary>O seletor devolveu nulo — nao ha cliente para o par alias/protocolo.</summary>
+    public static AgentFactoryException NoChatClient(string alias, AgentApi api)
+        => new(
+            AgentFactoryError.NoChatClient,
+            $"alias '{alias}': {nameof(AgentFactoryOptions.ChatClientSelector)} devolveu nulo para o " +
+            $"protocolo '{api}'. Um cliente ausente e recusa explicita, nunca um agente sem cliente.");
+}

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

@@ -0,0 +1,91 @@
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+using Morph.AiKit.Providers;
+
+namespace Morph.AiKit.Agents;
+
+/// <summary>
+/// O que a <see cref="AgentFactory"/> precisa saber que NAO esta na
+/// <see cref="AgentSpec"/>: infraestrutura do processo (log, DI) e os tres encaixes do
+/// pipeline que outras tasks preenchem.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que encaixes e nao dependencias diretas:</b> a ORDEM do pipeline e do kit — ela
+/// esta escrita, medida e testada dentro da <see cref="AgentFactory"/>. O CONTEUDO de cada
+/// posicao e de quem tem o tipo: o middleware de custo mora na T11 e a telemetria na T12.
+/// Se a fabrica referenciasse os dois diretamente, ou ela nasceria depois deles, ou eles
+/// nasceriam dentro dela. Com encaixe nomeado, a fabrica continua dona do lugar e cada
+/// task continua dona do que ocupa o lugar.
+/// </para>
+/// <para>
+/// Encaixe nulo = posicao vazia. Um agente sem custo e sem telemetria e um agente valido,
+/// nao um agente pela metade.
+/// </para>
+/// </remarks>
+public sealed record AgentFactoryOptions
+{
+    /// <summary>
+    /// Fabrica de log repassada ao <c>FunctionInvokingChatClient</c> e ao
+    /// <c>ChatClientAgent</c>. Nula = sem log, que e o default do MAF.
+    /// </summary>
+    public ILoggerFactory? LoggerFactory { get; init; }
+
+    /// <summary>
+    /// Container usado para resolver servicos ao montar os pipelines. Nulo = os builders
+    /// do <c>Microsoft.Extensions.AI</c> usam o provider vazio deles.
+    /// </summary>
+    public IServiceProvider? ServiceProvider { get; init; }
+
+    /// <summary>
+    /// De onde sai o <see cref="IChatClient"/> quando o protocolo efetivo NAO e o do alias.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// O <c>ModelRegistry</c> memoiza <b>um</b> cliente por alias, construido pela
+    /// <c>IProviderClientFactory</c> a partir do <c>api:</c> daquele alias. Logo, uma spec
+    /// que pede Chat Completions num alias declarado <c>responses</c> nao pode ser servida
+    /// pelo cliente memoizado — ele fala o outro protocolo. Sem este seletor a fabrica
+    /// <b>recusa</b> a combinacao, nomeando os dois protocolos, em vez de devolver um agente
+    /// que diz falar um protocolo e fala outro.
+    /// </para>
+    /// <para>
+    /// Nulo (o normal) = todo agente usa o cliente memoizado do alias, e
+    /// <see cref="AgentSpec.Api"/> divergente vira recusa. Preenchido, recebe o alias e o
+    /// protocolo <b>efetivo</b> (ja resolvido por <see cref="AgentSpec.ResolveApi"/>) e
+    /// devolve o cliente correspondente.
+    /// </para>
+    /// </remarks>
+    public Func<ModelAlias, AgentApi, IChatClient>? ChatClientSelector { get; init; }
+
+    /// <summary>
+    /// Encaixe do middleware de custo (T11), <b>acima</b> do <c>FunctionInvokingChatClient</c>.
+    /// Preencha com <c>(b, _, alias) =&gt; b.UseUsageCost(alias, sink)</c>.
+    /// </summary>
+    /// <remarks>
+    /// A posicao e medida, nao opinada: acima do FICC o middleware ve <b>uma</b> resposta
+    /// com o uso ja somado de todas as voltas de tool (medido: 40/10 num roteiro de duas
+    /// voltas de 10/4 e 30/6); abaixo do FICC ele ve uma resposta por volta. Pior, o FICC
+    /// <b>acumula no proprio objeto</b> <c>UsageDetails</c> da primeira volta — um sink que
+    /// guardasse a referencia abaixo do FICC leria valores que mudaram depois.
+    /// </remarks>
+    public Func<ChatClientBuilder, AgentSpec, ModelAlias, ChatClientBuilder>? ConfigureUsageCost { get; init; }
+
+    /// <summary>
+    /// Encaixe da telemetria de chat (T12), <b>abaixo</b> do <c>FunctionInvokingChatClient</c>
+    /// e imediatamente acima do cliente do provider.
+    /// </summary>
+    /// <remarks>
+    /// A posicao e exigencia escrita do proprio MAF 1.20.0: com a instrumentacao abaixo do
+    /// FICC o span de chat fecha <b>antes</b> de as tools rodarem, o que deixa o
+    /// <c>invoke_agent</c> como span raiz e permite ao FICC emitir <c>execute_tool</c>.
+    /// </remarks>
+    public Func<ChatClientBuilder, AgentSpec, ModelAlias, ChatClientBuilder>? ConfigureChatTelemetry { get; init; }
+
+    /// <summary>
+    /// Encaixe da telemetria de agente (T12) — o span mais externo, que cobre a invocacao
+    /// inteira. Preencha com <c>(b, _, _) =&gt; b.UseMorphTelemetry(telemetryOptions)</c>.
+    /// </summary>
+    public Func<AIAgentBuilder, AgentSpec, ModelAlias, AIAgentBuilder>? ConfigureAgentTelemetry { get; init; }
+}