@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/framework/standards/ai-agents/agent-spec.md

@@ -0,0 +1,196 @@
+# Agent Spec — o agente como dado, não como construção espalhada
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** agent spec, AgentSpec, agent catalog, AgentCatalog, um agente por spec, defaults do agente, quantos agentes
+> **Read by Claude in:** implement (ao declarar ou alterar um agente) e plan (ao contar quantos agentes a feature cria)
+
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentSpec.cs`, `.../Agents/AgentSpecOptions.cs` e `.../Agents/AgentFactory.cs` — o record, o bag de opções e a materialização são exatamente o que o kit compila. Last-verified: 2026-09-08.
+
+---
+
+## O agente como dado
+
+**Este standard possui:** a **forma do record** que descreve um agente, o **catálogo** que os
+enumera, e a regra **"nulo = não envia"**. Ele **não** possui: timeout, retry, strict e temperatura
+como valores de runtime (`ai-agents-llm-runtime-defaults`), tarifa e teto de custo
+(`ai-agents-cost-and-budget`), a origem do texto de `Instructions`
+(`ai-agents-prompt-sources`), nem o **schema** do arquivo de registry
+(`ai-agents-providers-model-registry`, Layer 0). Os cinco descrevem **um** artefato; a fronteira
+está escrita nos cinco para que ninguém precise adivinhar onde um campo mora.
+
+A dor que este standard mata é de **contagem**. Quando o agente é construído inline em cada
+call-site, ninguém no projeto consegue responder três perguntas triviais:
+
+1. Quantos agentes existem?
+2. Cada um roda com que modelo, e com que esforço de raciocínio?
+3. Onde está o default que vale de verdade?
+
+Medição de campo que motiva a regra: num projeto do acervo o agente é construído em **cinco
+lugares distintos**, e os defaults **divergem do que roda** — um call-site diz um modelo, o
+`appsettings.json` diz outro, e a documentação de arquitetura do próprio projeto ainda registra o
+primeiro. No mesmo projeto, acrescentar um campo de spec exige **seis pontos de wiring, cinco dos
+quais falham em silêncio**.
+
+A forma que resolve: **um agente, uma spec**. A spec é um `record` imutável, sem comportamento de
+execução, que não abre conexão e não lê configuração — o que permite descrevê-lo em teste, em JSON
+ou em banco sem arrastar infraestrutura junto.
+
+---
+
+## AgentSpec
+
+Os campos, medidos no record que o kit compila:
+
+| Campo | Tipo | Regra |
+|---|---|---|
+| `Alias` | `string` **required** | Chave no registry, **nunca** um id de modelo. Vazio ou só espaço é rejeitado **na construção** |
+| `Instructions` | `string` **required** | Prompt de sistema. Vazio ou só espaço é rejeitado na construção |
+| `Api` | `AgentApi?` | Protocolo desta spec. **Nulo = usa o `api:` do alias**, que é o caso normal |
+| `Tools` | `IReadOnlyList<AITool>` | Vazio por padrão — **nunca nulo** |
+| `OutputSchema` | `JsonElement?` | Nulo = saída livre |
+| `Options` | `AgentSpecOptions` | Bag único de opções. Nunca nulo; o default não envia opção nenhuma |
+| `Name` | `string?` | Nome legível (telemetria, logs) |
+| `Description` | `string?` | Descrição legível |
+
+**Duas decisões de forma que valem mais que a lista.**
+
+**(1) Validar na construção, não no uso.** `Alias` e `Instructions` rejeitam branco no `init`. Um
+alias vazio que passa da construção vira uma falha de resolução ilegível várias camadas adiante,
+num stack trace que não menciona o agente.
+
+**(2) A precedência mora num lugar só.** Quando a spec traz `Api` e o alias traz outro, quem vence?
+A resposta é um método no próprio record — `ResolveApi(aliasApi) => Api ?? aliasApi` — e **não** uma
+condicional dentro da fábrica. O motivo é escrito no kit: divergência silenciosa entre spec e
+registry é exatamente o bug que o `api:` por alias existe para eliminar, e uma regra copiada em dois
+lugares é uma regra que já divergiu.
+
+### A regra que este standard torna doutrina: nulo = não envia
+
+**Propriedade nula significa "não envia ao provider" — nunca "envia o default do framework".**
+
+Sem essa regra, cada propriedade opcional carrega uma segunda pergunta invisível: *o framework
+preenche isso por mim?* Com ela, a leitura é local e total: o que está nulo não aparece na chamada,
+e o que aparece na chamada é o que alguém escreveu.
+
+O corolário incômodo, e ele é parte da regra: **dentro de `Options`, lista vazia não é tratada como
+nulo**. `[]` é enviado como veio — `StopSequences` é o exemplar: o kit testa `is not null`, não
+`Count > 0`.
+
+**E há exatamente uma exceção, que este standard nomeia em vez de esconder.** `Tools` não vive em
+`Options`: vive na própria `AgentSpec`, é `IReadOnlyList<AITool>` (nunca nulo, vazio por padrão), e o
+kit a copia sob `if (spec.Tools.Count > 0)` — medido em `AgentFactory.cs`. Consequência: um
+`Tools = []` **explícito** não chega ao `ChatOptions`, e o provider recebe a chamada sem lista de
+tools em vez de com uma lista vazia.
+
+Isso é defensável (uma lista vazia enviada muda o comportamento de alguns providers) e é **por isso**
+que precisa estar escrito: a regra "nulo não envia; não-nulo envia o que você escreveu" vale
+**dentro de `Options`**; em `Tools`, o vazio também não envia, porque ali não existe nulo para
+distinguir do vazio. Uma exceção nomeada é uma regra; uma exceção não nomeada é o tipo de coisa que
+só se descobre lendo a fatura.
+
+O segundo corolário: quando `Options` não traz o esforço de raciocínio, vale **o default do
+provider**, e o kit **não afirma saber qual é**. Não saber e dizer que não sabe é mais barato do que
+documentar um default que o provider muda sem avisar.
+
+---
+
+## AgentCatalog
+
+Um lugar que responde: *quantos agentes existem, com que alias, e com que opções*. É o que
+transforma "cinco call-sites" em "cinco linhas de uma lista".
+
+O catálogo é **enumerável** e **inerte**: ele não constrói agentes, ele os declara. Construir é da
+fábrica.
+
+> **Item de catálogo sem consumidor em runtime é letra morta.** Precedente medido: um agente
+> seedado por migration, com prompt versionado no banco, **sem nenhum consumidor em C#** —
+> aparecendo apenas como alias fictício num arquivo de teste. Ele custou uma migration, ocupa uma
+> linha na tabela de prompts e responde por zero comportamento.
+
+Por isso a regra é dupla: todo agente do catálogo **é referenciado por um caminho de execução**, e
+todo agente executado **está no catálogo**. Uma verificação barata é contar: quantidade de entradas
+no catálogo × quantidade de call-sites que resolvem uma entrada. Divergência é achado, não ruído.
+
+---
+
+## Defaults fora do código
+
+O default do agente mora **na configuração do registry**, não num literal. Um valor default escrito
+em C# é invisível para quem lê o JSON, e um valor no JSON é invisível para quem lê o C# — ter os
+dois é garantir que um deles esteja errado.
+
+Regras:
+
+- O alias default é declarado no documento do registry (`defaultAlias`), não escolhido por um `??`
+  em algum handler.
+- Um limite conhecido de um alias (por exemplo, "este modelo rejeita tool calling com esforço de
+  raciocínio diferente de `None`") é **campo do alias, com procedência escrita**, nunca uma regra
+  universal chumbada no código. O kit recusa carregar um limite sem procedência — justamente para
+  que ninguém consiga gravar um "todo mundo sabe que" sem dizer de onde tirou.
+- Quando um default do provider é desconhecido, o correto é **não enviar** e não documentar palpite.
+
+---
+
+## Higiene de publicação
+
+O documento do registry é **arquivo de produção**. Override de desenvolvimento não mora nele.
+
+Os dois lados foram medidos no acervo:
+
+| Prática | O que aconteceu |
+|---|---|
+| **Anti-padrão** | Um alias apontando para um modelo local foi **commitado** no registry, com o comentário `"OVERRIDE LOCAL (teste com Ollama) — NÃO COMMITAR"` ao lado. O comentário estava certo; o commit aconteceu do mesmo jeito |
+| **Padrão** | Outro projeto mantém deliberadamente o override de endpoint e de modelo **fora** do registry, em configuração de ambiente, com a razão escrita no código: *"o JSON também vale em produção"* |
+
+A regra: o que vale nas duas pontas vai no registry; o que vale só na sua máquina vai em
+configuração de ambiente ou em `appsettings.Development.json`, que não é publicado. Um comentário
+avisando para não commitar não é um mecanismo — é uma esperança.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Agente construído inline em cada call-site | Ninguém consegue responder "quantos agentes existem" nem "com que modelo" | Uma `AgentSpec` por agente, num catálogo |
+| Id de modelo dentro da spec | Trocar de provider vira uma varredura; o registry deixa de ser fonte | `Alias`, sempre |
+| Default do agente escrito como literal em C# | Duas fontes para o mesmo valor, e uma delas está errada | Default no documento do registry |
+| Nulo interpretado como "manda o default do framework" | A chamada passa a carregar valores que ninguém escreveu | Nulo = não envia. Sem exceção |
+| Lista vazia tratada como nula **sem a exceção nomeada** | A regra deixa de ser local: quem lê não sabe que `Tools = []` não chega ao provider | `[]` é enviado como veio dentro de `Options`; a exceção de `Tools` fica escrita |
+| Precedência spec × alias resolvida dentro da fábrica | A regra copiada em dois lugares já divergiu | Um método no próprio record |
+| Entrada de catálogo sem consumidor em runtime | Migration paga, linha na tabela, zero comportamento | Toda entrada é referenciada por um caminho de execução |
+| Override de dev commitado no registry | O arquivo vale em produção; o override vaza | Override fora do arquivo publicado |
+| Validação de `Alias`/`Instructions` adiada para o uso | Falha ilegível várias camadas adiante | Rejeite branco no `init` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Existe exatamente **uma** `AgentSpec` por agente, e nenhum agente é construído inline
+- [ ] Nenhuma spec contém id de modelo — só `Alias`
+- [ ] `Alias` e `Instructions` são validados na construção (branco é rejeitado ali)
+- [ ] A precedência entre o `api:` da spec e o do alias existe em **um** lugar
+- [ ] Toda propriedade opcional nula **não** é enviada ao provider; nenhum código preenche default
+      de framework por baixo
+- [ ] Toda exceção à regra "não-nulo envia o que você escreveu" está **nomeada** no standard do
+      projeto (no exemplar do kit há exatamente uma: `Tools = []` não é enviada)
+- [ ] O catálogo enumera todos os agentes, e toda entrada tem ao menos um consumidor em runtime
+- [ ] O `defaultAlias` está no documento do registry, não num `??` de handler
+- [ ] Nenhum override de desenvolvimento no arquivo de registry publicado
+
+---
+
+## References
+
+- `ai-agents-providers-model-registry` — Layer 0, dono do **schema** do documento, do `defaultAlias`,
+  do fallback e da tabela de providers. Este standard não repete nada disso
+- `ai-agents-setup` — pacotes e `Program.cs`; a construção provider a provider é lá
+- `ai-agents-agent-archetypes` — qual **forma** de agente a spec descreve
+- `ai-agents-llm-runtime-defaults` — timeout, retry, strict, temperatura e o pin de SDK
+- `ai-agents-cost-and-budget` — `pricing` por alias, cálculo e teto
+- `ai-agents-prompt-sources` — de onde vem o texto de `Instructions`, e como provar qual versão rodou
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-spec.md v1.0 (2026-09-08)*

package/framework/standards/ai-agents/batching.md

@@ -5,7 +5,7 @@
 > **Keywords:** batching, batch api, bulk prompts, batch processing, async batch
 > **Read by Claude in:** plan/implement
 
-**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.* (fluxo da Batch API confirmado pela REST API; nomes de tipos/métodos .NET marcados `// VERIFY:` — ver seção A API). Last-verified: 2026-05-19.
+**Verified against:** OpenAI 2.13.0 (ai-pin 2026-09-08) + Microsoft.Extensions.AI 10.9.0. **Verificação documental** do fluxo da Batch API (platform.openai.com/docs/guides/batch, lido 2026-09-08), sem cláusula `provado por`: o ai-kit **referencia** o pacote `OpenAI` no `.csproj` — contrato de versão, régua = restore (`NU1102`) — mas **não o exercita**; não existe um único `using OpenAI` em `src/` (medido 2026-09-08), logo um rename de API não reprova a PR. Ver a tabela "Dois níveis de garantia" no README do kit. **Todos os nomes de tipo e assinaturas .NET foram medidos por reflexão sobre a assembly `OpenAI` 2.13.0 em 2026-09-08**, e os 9 marcadores `// VERIFY` desta página foram RESOLVIDOS por essa medição. Last-verified: 2026-09-08.
 
 ---
 
@@ -35,20 +35,24 @@ Use a Batch API quando você tem **N prompts independentes sem necessidade de re
 
 O fluxo tem 4 etapas: **upload do arquivo JSONL → submissão do batch → poll de status → download dos resultados**.
 
-> ### ⚠️ Status de verificação da API .NET
->
-> O fluxo abaixo é o **padrão correto da OpenAI Batch API** (confirmado pela REST API e pelos
-> docs oficiais). O que **não** foi confirmável via context7 são os nomes exatos de tipos/métodos
-> do **OpenAI .NET SDK 2.\*** para batch — o context7 retornou apenas as APIs de Assistants/Files.
->
-> **Confirmado:** `openAIClient.GetOpenAIFileClient()` → `OpenAIFileClient`; upload de arquivo
-> via `UploadFileAsync(stream, filename, FileUploadPurpose.*)`.
->
-> **A confirmar contra o pacote `OpenAI` 2.\* instalado** (todos marcados `// VERIFY:` no código):
-> nome do método que retorna o batch client (`GetBatchClient()`), namespace do batch
-> (`OpenAI.Batch`), assinatura de `CreateBatchAsync`, nomes de `GetBatchAsync`/`DownloadFileAsync`,
-> tipo/valores do status, e o valor de `FileUploadPurpose` para batch.
-> **Antes de codar:** abra o pacote no IntelliSense ou no [openai-dotnet](https://github.com/openai/openai-dotnet) e confirme cada `// VERIFY:`.
+### A superfície real do SDK 2.13.0 — medida, não suposta
+
+A versão anterior deste standard marcava sete nomes como "a confirmar". Foram conferidos por reflexão sobre a assembly do pin em 2026-09-08. O resultado corrige mais do que confirma:
+
+| O que estava escrito | O que a assembly 2.13.0 diz |
+|---|---|
+| `openAIClient.GetBatchClient()` (talvez `GetOpenAIBatchClient()`) | **`GetBatchClient()`** ✔ — devolve `OpenAI.Batch.BatchClient` |
+| namespace `OpenAI.Batch` | ✔ existe (`BatchClient`, `BatchJob`, `CreateBatchOperation`, `BatchCollectionOptions`) |
+| `FileUploadPurpose.Batch` | ✔ existe (ao lado de `Assistants`, `FineTune`, `Vision`, `UserData`, `Evaluations`) |
+| `fileClient.UploadFileAsync(stream, filename, purpose)` | ✔ existe, com essa exata assinatura |
+| `fileClient.DownloadFileAsync(fileId)` | ✔ existe — devolve `ClientResult<BinaryData>` |
+| `CreateBatchAsync(fileId, endpoint, completionWindow)` | ✘ **NÃO EXISTE.** A assinatura real é `CreateBatchAsync(BinaryContent content, bool waitUntilCompleted, RequestOptions options)` — método de **protocolo**: o corpo do request é montado por você |
+| tipo de retorno `OpenAIBatch` | ✘ **não existe.** O modelo é **`BatchJob`**; e `CreateBatchAsync` devolve **`CreateBatchOperation`** |
+| `GetBatchAsync(id)` com `Status` tipado | ✘ **`GetBatchAsync(string batchId, RequestOptions options)` devolve `ClientResult` cru.** Além disso `BatchJob.Status` é do tipo **`InternalBatchStatus`**, que **não é exportado**: mesmo desserializando o `BatchJob`, o consumidor não consegue nomear o tipo do status |
+
+**A conclusão que muda o código:** no `OpenAI` 2.13.0, **Batch é uma API de protocolo, não de modelo**. Você monta o corpo do request e lê o status do **JSON da resposta**. Um exemplo escrito com opções fortemente tipadas não compila — e essa era exatamente a dúvida que os `// VERIFY` marcavam.
+
+`CreateBatchOperation` traz `BatchId`, `GetBatchAsync()`, `CancelAsync()` e `RehydrationToken` — este último é o que permite **retomar o acompanhamento depois de um restart** sem guardar estado próprio: guarde o token, reidrate com `CreateBatchOperation.RehydrateAsync(client, token)`.
 
 ---
 
@@ -56,17 +60,18 @@ O fluxo tem 4 etapas: **upload do arquivo JSONL → submissão do batch → poll
 
 ```csharp
 using OpenAI;
-using OpenAI.Batch;   // VERIFY namespace — confirme contra o pacote OpenAI 2.* instalado
+using OpenAI.Batch;
 using OpenAI.Files;
 using System.ClientModel;
+using System.ClientModel.Primitives;
 using System.Text;
 using System.Text.Json;
 
 // ── 1. Construir o cliente OpenAI direto (mesma config que o Model Registry usa) ──
 var apiKey = configuration["OpenAI:ApiKey"]!;
 var openAIClient = new OpenAIClient(new ApiKeyCredential(apiKey));
-var fileClient = openAIClient.GetOpenAIFileClient();   // confirmado
-var batchClient = openAIClient.GetBatchClient();   // VERIFY método — pode ser GetOpenAIBatchClient()
+OpenAIFileClient fileClient  = openAIClient.GetOpenAIFileClient();
+BatchClient      batchClient = openAIClient.GetBatchClient();
 
 // ── 2. Montar o arquivo JSONL com N requests independentes ──
 var items = new[] { "Item A", "Item B", "Item C" }; // substitua pela sua coleção
@@ -92,32 +97,44 @@ foreach (var item in items)
 }
 
 // ── 3. Upload do arquivo JSONL ──
-var jsonlBytes = Encoding.UTF8.GetBytes(jsonlBuilder.ToString());
-using var jsonlStream = new MemoryStream(jsonlBytes);
-// VERIFY valor do enum — FileUploadPurpose.Batch (confirme; o SDK 2.* expõe outros purposes)
+using var jsonlStream = new MemoryStream(Encoding.UTF8.GetBytes(jsonlBuilder.ToString()));
 OpenAIFile batchFile = await fileClient.UploadFileAsync(
     jsonlStream, "batch_requests.jsonl", FileUploadPurpose.Batch);
 
 // ── 4. Submeter o batch ──
-// VERIFY assinatura de CreateBatchAsync — provável (fileId, endpoint, completionWindow)
-var batch = await batchClient.CreateBatchAsync(
-    batchFile.Id,
-    endpoint: "/v1/chat/completions",
-    completionWindow: "24h");
+// CreateBatchAsync é método de PROTOCOLO: o corpo vai como BinaryContent.
+// waitUntilCompleted: false → devolve a operação imediatamente (o poll é seu, no §5).
+using var createBody = BinaryContent.Create(BinaryData.FromObjectAsJson(new
+{
+    input_file_id    = batchFile.Id,
+    endpoint         = "/v1/chat/completions",
+    completion_window = "24h",
+}));
+
+CreateBatchOperation operation =
+    await batchClient.CreateBatchAsync(createBody, waitUntilCompleted: false);
+
+string batchId = operation.BatchId;
+// Guarde operation.RehydrationToken se o poll roda em OUTRO processo/depois de um restart.
 
 // ── 5. Poll de status (em background job / Hangfire / Worker) ──
-OpenAIBatch? completedBatch = null;   // VERIFY nome do tipo de retorno
+// GetBatchAsync devolve ClientResult cru, e BatchJob.Status é de um tipo NÃO EXPORTADO
+// (InternalBatchStatus). O status se lê do JSON — não há caminho tipado no 2.13.0.
+string status;
+JsonElement batchDoc;
 do
 {
     await Task.Delay(TimeSpan.FromSeconds(30)); // poll interval para batch — não interativo
-    completedBatch = await batchClient.GetBatchAsync(batch.Id);   // VERIFY nome do método
-} while (completedBatch?.Status is not ("completed" or "failed" or "cancelled"));   // VERIFY tipo/valores do Status
+    ClientResult raw = await batchClient.GetBatchAsync(batchId, options: null);
+    batchDoc = JsonDocument.Parse(raw.GetRawResponse().Content.ToMemory()).RootElement;
+    status = batchDoc.GetProperty("status").GetString()!;
+} while (status is not ("completed" or "failed" or "cancelled" or "expired"));
 
 // ── 6. Recuperar e processar resultados ──
-if (completedBatch?.OutputFileId is { } outputFileId)
+if (batchDoc.TryGetProperty("output_file_id", out var outEl) && outEl.GetString() is { } outputFileId)
 {
-    var resultFile = await fileClient.DownloadFileAsync(outputFileId);   // VERIFY nome do método
-    using var reader = new StreamReader(resultFile.Value.ToStream());
+    BinaryData resultFile = await fileClient.DownloadFileAsync(outputFileId);
+    using var reader = new StreamReader(resultFile.ToStream());
     string? line;
     while ((line = await reader.ReadLineAsync()) is not null)
     {
@@ -135,15 +152,17 @@ if (completedBatch?.OutputFileId is { } outputFileId)
 }
 
 // ── 7. Tratar falhas de itens individuais ──
-if (completedBatch?.ErrorFileId is { } errorFileId)
+if (batchDoc.TryGetProperty("error_file_id", out var errEl) && errEl.GetString() is { } errorFileId)
 {
-    var errorFile = await fileClient.DownloadFileAsync(errorFileId);   // VERIFY nome do método
+    BinaryData errorFile = await fileClient.DownloadFileAsync(errorFileId);
     // log itens que falharam; retente individualmente se necessário
 }
 ```
 
 > O poll de status (`do...while`) deve rodar num **background job** (Hangfire, Worker Service),
 > não em uma requisição HTTP. O usuário não espera; o resultado é entregue via event/webhook/DB.
+> Se o job pode reiniciar, persista `operation.RehydrationToken` e retome com
+> `CreateBatchOperation.RehydrateAsync(batchClient, token)` em vez de guardar só o `batchId`.
 
 ---
 
@@ -166,6 +185,9 @@ if (completedBatch?.ErrorFileId is { } errorFileId)
 | Não tratar `error_file_id` | Itens que falharam são silenciados; reprocessamento nunca acontece |
 | Poll com `Task.Delay(1s)` em loop | Abuso de rate limits; use intervalo ≥ 30 s para batch |
 | Assumir que todos os itens do batch concluem | Batch pode ter falhas parciais; itere o arquivo de erros |
+| Escrever `CreateBatchAsync(fileId, endpoint, completionWindow)` | Essa sobrecarga não existe no `OpenAI` 2.13.0 — o método é de protocolo e recebe `BinaryContent` |
+| Tipar o status como `OpenAIBatch.Status` | `OpenAIBatch` não existe; `BatchJob.Status` é de um tipo não exportado. Leia o status do JSON |
+| Guardar só o `batchId` num job que pode reiniciar | Perde o acompanhamento da operação | 
 | Incluir prompt com dados do usuário sem sanitização | Prompt injection em batch; aplique `ai-agents-middleware-patterns` |
 
 ---
@@ -176,7 +198,9 @@ if (completedBatch?.ErrorFileId is { } errorFileId)
 - [ ] O poll de status roda em background job (Worker/Hangfire), não em request HTTP
 - [ ] `error_file_id` é verificado e erros de itens individuais são logados/retentados
 - [ ] Nenhum `Guid.NewGuid()` — custom_id usa `Guid.CreateVersion7()`
-- [ ] Provider é OpenAI; cada `// VERIFY:` da API .NET de batch confirmado contra o pacote instalado antes de codar
+- [ ] Provider é OpenAI, com `PackageReference Include="OpenAI" Version="2.13.0"` (versão exata)
+- [ ] O status do batch é lido do JSON da resposta — nenhum código tenta tipar `Status` ou usar `OpenAIBatch`
+- [ ] `waitUntilCompleted: false` + poll próprio, ou `RehydrationToken` persistido se o poll pode reiniciar
 
 ---
 
@@ -186,8 +210,8 @@ if (completedBatch?.ErrorFileId is { } errorFileId)
 - `ai-agents-service-tier-flex` — otimização de custo para jobs async
 - `ai-agents-providers-model-registry` — configuração provider-agnostic
 - OpenAI Batch API: https://platform.openai.com/docs/guides/batch
-- OpenAI .NET SDK `OpenAI.Batch`: https://github.com/openai/openai-dotnet
+- OpenAI .NET SDK `OpenAI.Batch`: https://github.com/openai/openai-dotnet (superfície medida na assembly 2.13.0 em 2026-09-08)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/batching.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/batching.md v2.0 (2026-09-08)*

package/framework/standards/ai-agents/context-providers.md

@@ -2,16 +2,57 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 2 (on-keyword)
-> **Keywords:** context provider, dynamic context, context injection, AIContextProvider, memory provider
+> **Keywords:** context provider, dynamic context, context injection, AIContextProvider, memory provider, compaction, ordem de escolha, plano por fase
 > **Read by Claude in:** implement
 
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+**Verified against:** Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08) + doc oficial de context providers e de compaction (learn.microsoft.com, `ms.date` 2026-07-30). **Verificação documental** para o desenho — o ai-kit não registra `AIContextProvider`; os nomes de tipo, o pacote de cada extensão e o atributo `[Experimental]` da compaction foram **medidos por reflexão sobre `Microsoft.Agents.AI` 1.20.0** em 2026-09-08. Last-verified: 2026-09-08.
+
+---
+
+## Ordem de escolha — a tool vem primeiro
+
+**A regra, antes de qualquer API:** comece pela **tool**. Só suba para um `AIContextProvider` quando o contexto é **transversal** — memória, compaction, tenant, segurança — *e* o LLM **não pode ter a opção** de não buscá-lo.
+
+```
+Preciso que o agente saiba X.
+├─ O LLM deve decidir SE precisa de X? ──────────────→ TOOL
+├─ X depende do que foi perguntado (similaridade)? ──→ RAG (dentro de uma tool)
+├─ X vale para TODO turno e o LLM não pode pular? ───→ AIContextProvider
+└─ X muda o MODO do agente (instruções + tools
+   permitidas por fase do funil)? ──────────────────→ compositor determinístico em C#
+                                                      (nem provider, nem tool)
+```
+
+**O caso concreto que a regra evita:** RAG passivo injetado como context provider. O usuário digita "oi" e o agente paga uma busca vetorial + o custo dos trechos no prompt — **em todo turno**, inclusive nos que não precisam de conhecimento nenhum. Como tool, o "oi" não dispara busca alguma. Foi medido em produção: o escopo institucional da base do GHLBrain roda sem `LIMIT`, e passivo isso é custo por turno, não por necessidade.
+
+### O compositor determinístico — a alternativa que não é provider
+
+Plano por fase (instruções + **allow-list de tools** conforme o estado do funil) **não** é caso de provider. É C# puro, montado antes de criar a requisição:
+
+```csharp
+// O CÓDIGO decide o modo; o LLM só classifica. A allow-list de tools é a parte
+// que um provider não consegue dar: AIContext.Tools ACRESCENTA tools, não remove.
+public sealed record OperatorPlan(string Instructions, IReadOnlyList<AITool> Tools);
+
+public static OperatorPlan PlanFor(FunnelStage stage) => stage switch
+{
+    FunnelStage.Triage    => new(TriagePrompt,    [ClassifyLead, ScheduleCall]),
+    FunnelStage.Quoting   => new(QuotingPrompt,   [ClassifyLead, BuildQuote, ScheduleCall]),
+    FunnelStage.Closing   => new(ClosingPrompt,   [BuildQuote, SendContract]),
+    _                     => new(DefaultPrompt,   [ClassifyLead]),
+};
+
+var plan = PlanFor(conversation.Stage);
+var options = new ChatOptions { Instructions = plan.Instructions, Tools = [.. plan.Tools] };
+```
+
+É a prática do GHLBrain (`OperatorPlan`) e o padrão do canal: **o código decide o modo, o LLM classifica**. Um provider que "sugere" quais tools usar deixa a decisão com o modelo; a allow-list tira a decisão do modelo.
 
 ---
 
 ## Quando usar Context Provider
 
-Use um `AIContextProvider` quando o agente precisa de **contexto dinâmico computado a cada chamada** — informação que varia por request, sessão ou tenant, sem poluir as instructions estáticas do agente.
+Use um `AIContextProvider` quando o agente precisa de **contexto dinâmico computado a cada chamada** — informação que varia por request, sessão ou tenant, sem poluir as instructions estáticas do agente — **e** a regra de ordem acima já descartou tool e compositor.
 
 **Exemplos de uso correto:**
 - Data/hora atual injetada nas instructions ("Today is Monday, 2026-05-19")
@@ -34,19 +75,20 @@ Use um `AIContextProvider` quando o agente precisa de **contexto dinâmico compu
 
 ## A API
 
-**Pacote:** `Microsoft.Agents.AI` + `Microsoft.Agents.AI.Hosting` (para o builder).
+**Pacote: `Microsoft.Agents.AI` 1.20.0 — e só ele.** Correção medida em 2026-09-08: a extensão `UseAIContextProviders` **não** vem de `Microsoft.Agents.AI.Hosting`; ela é publicada por `Microsoft.Extensions.AI.AIContextProviderChatClientBuilderExtensions`, **que está dentro da assembly `Microsoft.Agents.AI`** (o `using` é `Microsoft.Extensions.AI`, o pacote é `Microsoft.Agents.AI`). A versão anterior deste standard atribuía o método ao pacote errado.
 
-**Tipos confirmados via context7:**
+**Tipos e membros — medidos por reflexão sobre as assemblies do pin:**
 
-```
-AIContextProvider     — classe base abstrata (sealed override ProvideAIContextAsync + StoreAIContextAsync)
-AIContext             — objeto retornado; contém Messages, Instructions, etc.
-InvokingContext       — contexto disponível no before-run hook (acesso à session, mensagens atuais)
-InvokedContext        — contexto disponível no after-run hook (request + response messages)
-ProviderSessionState<T> — helper tipado para armazenar estado por provider na AgentSession
-ChatClientAgentOptions.AIContextProviders — lista de providers passados na construção do agente
-.UseAIContextProviders(...) — extension method via builder (Microsoft.Agents.AI.Hosting)
-```
+| Símbolo | Assembly | Nota |
+|---|---|---|
+| `AIContextProvider` | `Microsoft.Agents.AI.Abstractions` | Classe base **abstrata**. Overrides: `ProvideAIContextAsync(InvokingContext, ct)` e `StoreAIContextAsync(InvokedContext, ct)`, ambos `protected` |
+| `AIContext` | `Microsoft.Agents.AI.Abstractions` | **Exatamente três** propriedades: `Instructions`, `Messages`, `Tools` |
+| `AIContextProvider.InvokingContext` / `.InvokedContext` | idem | Tipos **aninhados** no provider (`AIContextProvider+InvokingContext`) |
+| `ProviderSessionState<TState>` | idem | `StateKey`, `GetOrInitializeState(session)`, `SaveState(session, state)` |
+| `AgentRequestMessageSourceType` | idem | Struct com `External`, `ChatHistory`, `AIContextProvider` |
+| `ChatClientAgentOptions.AIContextProviders` | `Microsoft.Agents.AI` | `IEnumerable<AIContextProvider>` |
+| `UseAIContextProviders(this ChatClientBuilder, params AIContextProvider[])` | `Microsoft.Agents.AI` | Registra **no pipeline de chat** — ver a diferença abaixo |
+| `Microsoft.Agents.AI.Compaction.*` | `Microsoft.Agents.AI` | **`[Experimental("MAAI001")]`** — medido no atributo do tipo |
 
 **Método a sobrescrever:**
 
@@ -55,6 +97,27 @@ ChatClientAgentOptions.AIContextProviders — lista de providers passados na con
 // StoreAIContextAsync    → chamado APÓS o LLM (after-run hook) — persiste estado se necessário
 ```
 
+### A invariante de instância — a mesma de `ai-agents-agent-session`
+
+**Um provider, uma instância, todas as sessões.** O provider não pode ter campo de estado por conversa; o que é por sessão vive em `ProviderSessionState<TState>` com o `StateKey` declarado em `StateKeys`. Campo de instância guardando "o tenant atual" é como o contexto de um cliente aparece no prompt de outro — e a falha não aparece em teste de uma sessão só, aparece sob concorrência.
+
+### `AgentRequestMessageSourceType` — como não fechar um loop
+
+Mensagem devolvida em `AIContext.Messages` volta ao agente marcada com a origem `AIContextProvider`; mensagem do usuário é `External`; a que veio do acervo é `ChatHistory`. **Um provider que reinjeta o que ele mesmo produziu no turno anterior monta um loop de crescimento.** Filtre por origem antes de reinjetar.
+
+### Compaction — experimental, e o lugar de registro muda o resultado
+
+`Microsoft.Agents.AI.Compaction.CompactionProvider` é um `AIContextProvider` marcado **`[Experimental("MAAI001")]`** (medido no atributo do tipo em 1.20.0): usá-lo exige `#pragma warning disable MAAI001` ou `<NoWarn>`. Estratégias disponíveis: `SummarizationCompactionStrategy`, `SlidingWindowCompactionStrategy`, `TruncationCompactionStrategy`, `ToolResultCompactionStrategy`, `ContextWindowCompactionStrategy`, `PipelineCompactionStrategy`; gatilhos em `CompactionTriggers` (`MessagesExceed`, `TokensExceed`, `TurnsExceed`, `GroupsExceed`, `HasToolCalls`, `Always`/`Never`, `Any`/`All`).
+
+**Onde registrar importa, e a diferença não é cosmética:**
+
+| Registro | Efeito |
+|---|---|
+| `chatBuilder.UseAIContextProviders(compaction)` (no `ChatClientBuilder`) | Compacta **só o request em voo**. O acervo persistido fica intacto |
+| `ChatClientAgentOptions.AIContextProviders = [compaction]` | **Não roda dentro do loop de tools**, e o resumo produzido **vaza para o histórico persistido** |
+
+Consequência prática: **compaction só faz sentido com histórico local**. Com a conversa no provedor (`store: true`) você compacta um lado e o outro continua inteiro. Ver `ai-agents-agent-session`.
+
 ---
 
 ## Exemplo C# — context provider que injeta data atual e perfil do tenant
@@ -124,10 +187,10 @@ builder.Services.AddSingleton<AIAgent>(sp =>
         });
 });
 
-// ── Alternativa: builder/middleware (útil para adicionar providers a agente existente) ──
-// var enrichedAgent = existingAgent
-//     .AsBuilder()
-//     .UseAIContextProviders(new TenantContextProvider(tenantSvc))
+// ── Alternativa: pipeline de chat (compacta/injeta SÓ o request em voo) ──
+// using Microsoft.Extensions.AI;   // a extensão vive na assembly Microsoft.Agents.AI
+// IChatClient enriched = chatClient.AsBuilder()
+//     .UseAIContextProviders(new TenantContextProvider(tenantSvc, tenantContext))
 //     .Build();
 
 // ── 3. Uso normal — provider é invocado automaticamente a cada RunAsync ──
@@ -161,6 +224,11 @@ Console.WriteLine(response.Text);
 | Injetar contexto gigante a cada chamada | Aumenta custo e pode esgotar context window; prefira tools para contexto on-demand |
 | Provider com side-effects de escrita em `ProvideAIContextAsync` | Hook before-run deve ser read-only; use `StoreAIContextAsync` para escrita |
 | Compartilhar estado mutável entre providers sem `ProviderSessionState<T>` | Race condition entre providers; use o helper tipado |
+| **Estado por sessão em campo do provider** | Uma instância atende todas as sessões: o contexto de um cliente vaza para outro. Use `ProviderSessionState<TState>` e declare o `StateKey` em `StateKeys` |
+| **RAG passivo como provider** | Paga busca vetorial e tokens de trecho em TODO turno, inclusive no "oi". RAG é tool |
+| **Provider para escolher tools por fase** | `AIContext.Tools` só ACRESCENTA — não existe allow-list por provider. Use o compositor determinístico (§Ordem de escolha) |
+| Reinjetar em `AIContext.Messages` o que o próprio provider produziu no turno anterior | Loop de crescimento. Filtre por `AgentRequestMessageSourceType` |
+| Compaction registrada em `ChatClientAgentOptions` esperando que rode no loop de tools | Ali ela não roda no loop, e o resumo vaza para o histórico persistido |
 | Usar Context Provider para lógica de negócio complexa | Providers devem ser leves e rápidos; lógica pesada vai em tools |
 
 ---
@@ -170,19 +238,24 @@ Console.WriteLine(response.Text);
 - [ ] O provider herda da classe base abstrata `AIContextProvider` (não implementa uma interface genérica)
 - [ ] `ProvideAIContextAsync` é read-only — sem writes a banco ou estado global
 - [ ] `StoreAIContextAsync` usado somente quando o provider precisa persistir estado
-- [ ] Provider registrado em `ChatClientAgentOptions.AIContextProviders` ou via `.UseAIContextProviders()`
-- [ ] Contexto injetado é **determinístico** — se depende de busca por similaridade, é RAG, não provider
+- [ ] Provider registrado em `ChatClientAgentOptions.AIContextProviders` ou via `.UseAIContextProviders()` — com o registro escolhido pela tabela de §Compaction, não por acaso
+- [ ] Contexto injetado é **determinístico** — se depende de busca por similaridade, é RAG (numa tool), não provider
+- [ ] A regra de ordem foi aplicada: existe uma frase dizendo por que **não** é uma tool
+- [ ] Nenhum campo de instância do provider guarda estado de conversa/tenant
+- [ ] Compaction (se usada) tem `MAAI001` suprimido conscientemente e o histórico é local
 
 ---
 
 ## References
 
 - `ai-agents-setup` — packages e DI base
-- `ai-agents-rag-custom-pgvector` (Onda 2) — busca por similaridade (distinto de context provider)
-- `ai-agents-multi-agent-patterns` (Onda 2) — composição de agentes
-- MAF Context Providers docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/context-providers
+- `ai-agents-agent-session` — a mesma invariante de instância, e por que compaction pede histórico local
+- `ai-agents-rag-custom-pgvector` — busca por similaridade (distinto de context provider)
+- `ai-agents-multi-agent-patterns` — composição de agentes
+- MAF Context Providers docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/context-providers (`ms.date` 2026-07-30)
+- MAF Compaction docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/compaction (`ms.date` 2026-07-30)
 - MAF Agent Pipeline docs: https://learn.microsoft.com/en-us/agent-framework/agents/agent-pipeline
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/context-providers.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/context-providers.md v2.0 (2026-09-08)*