@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

package/framework/templates/code/typescript/contracts.ts

@@ -1,167 +1,140 @@
-// ============================================================
-// CONTRACTS: {{titleCase FEATURE_NAME}}
-// Stack: Next.js + Neon
-// Generated by MORPH Framework
-// Date: {{DATE}}
-// ============================================================
-
-// ----- Neon Config -----
-
-export interface NeonConfig {
-  connectionString: string;
-}
-
-// ----- API Client Types -----
-
-export interface ApiClientConfig {
-  baseUrl: string;
-  getAccessToken: () => Promise<string | null>;
-}
-
-export interface ApiError {
-  message: string;
-  code: string;
-  statusCode: number;
-  details?: Record<string, string[]>;
-}
-
-export type ApiResult<T> =
-  | { success: true; data: T }
-  | { success: false; error: ApiError };
-
-// ----- Pagination -----
-
-export interface PaginationQuery {
-  page?: number;
-  pageSize?: number;
-}
-
-export interface PagedResult<T> {
-  items: T[];
-  totalCount: number;
-  page: number;
-  pageSize: number;
-  totalPages: number;
-  hasNext: boolean;
-  hasPrevious: boolean;
-}
-
-// ----- Database Client Type Aliases -----
-// Generated by your ORM (Drizzle or Prisma) from your Neon PostgreSQL schema
-
-export type Tables<T extends keyof Database["public"]["Tables"]> =
-  Database["public"]["Tables"][T]["Row"];
-
-export type Insertable<T extends keyof Database["public"]["Tables"]> =
-  Database["public"]["Tables"][T]["Insert"];
-
-export type Updatable<T extends keyof Database["public"]["Tables"]> =
-  Database["public"]["Tables"][T]["Update"];
-
-// ----- Database Schema (placeholder - replace with generated types) -----
-
-export interface Database {
-  public: {
-    Tables: {
-      {{FEATURE_NAME}}: {
-        Row: {
-          id: string;
-          name: string;
-          user_id: string;
-          status: {{pascalCase FEATURE_NAME}}Status;
-          created_at: string;
-          updated_at: string | null;
-        };
-        Insert: {
-          id?: string;
-          name: string;
-          user_id?: string;
-          status?: {{pascalCase FEATURE_NAME}}Status;
-          created_at?: string;
-          updated_at?: string | null;
-        };
-        Update: {
-          id?: string;
-          name?: string;
-          user_id?: string;
-          status?: {{pascalCase FEATURE_NAME}}Status;
-          created_at?: string;
-          updated_at?: string | null;
-        };
-      };
-    };
-    Views: Record<string, never>;
-    Functions: Record<string, never>;
-    Enums: {
-      {{FEATURE_NAME}}_status: {{pascalCase FEATURE_NAME}}Status;
-    };
-  };
-}
-
-// ----- Feature Types -----
-
-export type {{pascalCase FEATURE_NAME}}Status =
-  | "draft"
-  | "active"
-  | "completed"
-  | "archived"
-  | "failed"
-  | "cancelled";
-
-export interface {{pascalCase FEATURE_NAME}} {
-  id: string;
-  name: string;
-  userId: string;
-  status: {{pascalCase FEATURE_NAME}}Status;
-  createdAt: string;
-  updatedAt: string | null;
-}
-
-export interface Create{{pascalCase FEATURE_NAME}}Input {
-  name: string;
-  // Add other required fields
-}
-
-export interface Update{{pascalCase FEATURE_NAME}}Input {
-  name?: string;
-  // Add other updatable fields
-}
-
-// ----- Storage Types -----
-
-export interface StorageUpload {
-  bucket: string;
-  path: string;
-  file: File;
-  contentType?: string;
-}
-
-export interface StorageFile {
-  id: string;
-  name: string;
-  bucket: string;
-  path: string;
-  publicUrl: string;
-  size: number;
-  contentType: string;
-  createdAt: string;
-}
-
-// ----- Auth Types -----
-
-export interface AuthUser {
-  id: string;
-  email: string;
-  displayName: string | null;
-  avatarUrl: string | null;
-}
-
-export interface AuthSession {
-  user: AuthUser;
-  accessToken: string;
-  expiresAt: number;
-}
-
-// ----- Form Schemas (use with zod) -----
-// Define zod schemas in component files, not here.
-// This file is for type definitions only.
+// {{titleCase FEATURE_NAME}} contracts, generated {{DATE}}
+
+export interface NeonConfig {
+  connectionString: string;
+}
+
+export interface ApiClientConfig {
+  baseUrl: string;
+  getAccessToken: () => Promise<string | null>;
+}
+
+export interface ApiError {
+  message: string;
+  code: string;
+  statusCode: number;
+  details?: Record<string, string[]>;
+}
+
+export type ApiResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: ApiError };
+
+export interface PaginationQuery {
+  page?: number;
+  pageSize?: number;
+}
+
+export interface PagedResult<T> {
+  items: T[];
+  totalCount: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrevious: boolean;
+}
+
+export type Tables<T extends keyof Database["public"]["Tables"]> =
+  Database["public"]["Tables"][T]["Row"];
+
+export type Insertable<T extends keyof Database["public"]["Tables"]> =
+  Database["public"]["Tables"][T]["Insert"];
+
+export type Updatable<T extends keyof Database["public"]["Tables"]> =
+  Database["public"]["Tables"][T]["Update"];
+
+// Placeholder: replace with the types your ORM (Drizzle or Prisma) generates from the Neon schema.
+export interface Database {
+  public: {
+    Tables: {
+      {{FEATURE_NAME}}: {
+        Row: {
+          id: string;
+          name: string;
+          user_id: string;
+          status: {{pascalCase FEATURE_NAME}}Status;
+          created_at: string;
+          updated_at: string | null;
+        };
+        Insert: {
+          id?: string;
+          name: string;
+          user_id?: string;
+          status?: {{pascalCase FEATURE_NAME}}Status;
+          created_at?: string;
+          updated_at?: string | null;
+        };
+        Update: {
+          id?: string;
+          name?: string;
+          user_id?: string;
+          status?: {{pascalCase FEATURE_NAME}}Status;
+          created_at?: string;
+          updated_at?: string | null;
+        };
+      };
+    };
+    Views: Record<string, never>;
+    Functions: Record<string, never>;
+    Enums: {
+      {{FEATURE_NAME}}_status: {{pascalCase FEATURE_NAME}}Status;
+    };
+  };
+}
+
+export type {{pascalCase FEATURE_NAME}}Status =
+  | "draft"
+  | "active"
+  | "completed"
+  | "archived"
+  | "failed"
+  | "cancelled";
+
+export interface {{pascalCase FEATURE_NAME}} {
+  id: string;
+  name: string;
+  userId: string;
+  status: {{pascalCase FEATURE_NAME}}Status;
+  createdAt: string;
+  updatedAt: string | null;
+}
+
+export interface Create{{pascalCase FEATURE_NAME}}Input {
+  name: string;
+}
+
+export interface Update{{pascalCase FEATURE_NAME}}Input {
+  name?: string;
+}
+
+export interface StorageUpload {
+  bucket: string;
+  path: string;
+  file: File;
+  contentType?: string;
+}
+
+export interface StorageFile {
+  id: string;
+  name: string;
+  bucket: string;
+  path: string;
+  publicUrl: string;
+  size: number;
+  contentType: string;
+  createdAt: string;
+}
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+}
+
+export interface AuthSession {
+  user: AuthUser;
+  accessToken: string;
+  expiresAt: number;
+}

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

@@ -1,65 +1,18 @@
 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>
+    // 0 de proposito: default(AgentApi) e alias sem 'api:' caem em Responses; Chat e opt-in escrito.
     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

@@ -5,48 +5,11 @@ 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);
@@ -55,15 +18,6 @@ public sealed class AgentFactory
         _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);
@@ -71,11 +25,6 @@ public sealed class AgentFactory
         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);
@@ -98,6 +47,7 @@ public sealed class AgentFactory
             Name = spec.Name,
             Description = spec.Description,
             ChatOptions = BuildChatOptions(spec, alias),
+            // Com o default o ChatClientAgent monta o proprio FICC, sem MaximumIterationsPerRequest nem slot para o custo.
             UseProvidedChatClientAsIs = true,
         };
 
@@ -112,12 +62,6 @@ public sealed class AgentFactory
             : 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
@@ -151,6 +95,8 @@ public sealed class AgentFactory
             : throw AgentFactoryException.ProtocolWithoutSelector(alias.Name, alias.Api, api);
     }
 
+    // A ordem e o contrato: o custo fica ACIMA do FICC para ver o uso ja somado das voltas, e a
+    // telemetria de chat ABAIXO dele porque so assim o span de chat fecha antes das tools (MAF 1.20.0).
     private IChatClient BuildChatPipeline(IChatClient leaf, AgentSpec spec, ModelAlias alias)
     {
         var builder = leaf.AsBuilder();
@@ -186,11 +132,6 @@ public sealed class AgentFactory
         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(
@@ -222,43 +163,31 @@ public sealed class AgentFactory
     }
 }
 
-/// <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,
@@ -268,10 +197,6 @@ public sealed class AgentFactoryException : InvalidOperationException
             "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,
@@ -280,7 +205,6 @@ public sealed class AgentFactoryException : InvalidOperationException
             $"{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,

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

@@ -5,87 +5,18 @@ 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>
+    // Abaixo do FICC um sink veria uma resposta por volta, e o FICC muta o UsageDetails da primeira volta para acumular.
     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; }
 }