@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

package/framework/standards/ai-agents/conversational-agent-with-phases.md

@@ -0,0 +1,239 @@
+# Conversational Agent with Phases — um agente, fase como dado do turno
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (sob demanda)
+> **Keywords:** agente conversacional, fases do agente, allow-list de tools, RequireAny, ChatToolMode, compositor de turno, teto de tool calls, turno de conversa
+> **Read by Claude in:** implement (ao construir ou alterar um agente que atende uma conversa ao longo do tempo)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08). `ChatToolMode.RequireAny` foi **medido por reflexão sobre `Microsoft.Extensions.AI.Abstractions` 10.9.0** em 2026-09-08. O restante é **verificação documental**, sem cláusula `provado por` — o ai-kit ainda não traz um compositor de turno, e o padrão é destilado de um único repositório de campo (ver a nota de fonte única abaixo). Last-verified: 2026-09-08.
+
+---
+
+> **Nota de fonte única, declarada no corpo de propósito.** Todo o lastro de campo deste standard vem
+> de **um** repositório em produção. Não há segundo exemplar no acervo para confirmar nem para
+> contradizer. Isso não invalida o padrão — ele roda, e roda há tempo suficiente para ter dor
+> registrada —, mas muda como lê-lo: as **formas** aqui são fortes; os **números** (um teto de 8,
+> dois estágios de poda) são o que aquele produto precisou, não um universal. Onde este arquivo diz
+> "medido", leia "medido ali".
+
+---
+
+## Quando este arquétipo
+
+`ai-agents-agent-archetypes` decide a forma; este arquivo é o aprofundamento da primeira. Ele vale
+quando as quatro condições valem juntas:
+
+1. Há **um interlocutor** e uma conversa que dura mais de um turno.
+2. O que o agente **pode fazer** muda conforme o ponto da conversa.
+3. Existe estado observável de onde derivar esse ponto — não a memória do modelo.
+4. Toda ação com efeito no mundo é uma **tool**, não uma frase.
+
+Falhando (2), você tem um agente simples com histórico e não precisa de nada aqui. Falhando (4), o
+teto de tool calls e a allow-list perdem o sentido, porque a ação escapa pelo texto.
+
+---
+
+## Compositor de turno determinístico
+
+**A peça central, e a mais reaproveitável.** Um `static class` puro — sem I/O, sem relógio, sem
+banco — que recebe o estado do turno e devolve **um plano de turno**: as instruções, a lista de
+tools permitidas, e os limites daquele turno.
+
+Três propriedades definem o padrão:
+
+**(1) Prompt decomposto em blocos nomeados.** O prompt não nasce como uma string; nasce como uma
+lista de blocos com nome (`persona`, `contexto do lead`, `regras da fase`, `histórico`, …). O nome
+serve para medir: dá para dizer que bloco cresceu, que bloco entrou, que bloco não deveria estar ali.
+
+**(2) O texto enviado É a concatenação dos blocos, derivada sem cache.** Esta é a invariante, e ela
+é deliberadamente cara: nada de guardar a string montada ao lado dos blocos. A razão está escrita no
+código de campo: *"para a telemetria não poder mentir"*. Se o texto enviado e o texto registrado
+pudessem divergir — e um cache é exatamente um lugar onde divergem —, então o hash do prompt não
+prova mais nada, e a rastreabilidade inteira vira decoração. É o que amarra este standard a
+`ai-agents-observability-patterns`.
+
+**(3) Determinístico e puro, portanto testável sem infraestrutura.** Um compositor que lê banco não
+é testável em ciclo curto, e um compositor não testado é onde a regra de fase silenciosamente para
+de valer.
+
+**A dor que o compositor mata**, medida: montagem de prompt em **três lugares** e o filtro de
+allow-list em **três lugares** dentro do mesmo produto. Nenhum dos três está errado isoladamente;
+juntos, garantem que uma regra nova entre em dois e esqueça o terceiro.
+
+---
+
+## Allow-list por fase
+
+A poda acontece **em dois estágios, ambos em código**, e a ordem importa:
+
+| Estágio | Pergunta | Efeito |
+|---|---|---|
+| 1 | Esta tool pertence a **esta fase**? | Poda por fase |
+| 2 | Este **tenant/plano** tem esta capacidade? | Poda por capacidade |
+
+Regras que o campo fixou, e que valem repetir porque cada uma custou um bug:
+
+- O mapa de capacidade é **declarativo e puro** — uma tabela, não um `switch` com efeitos.
+- **Tool ausente do mapa é disponível.** O default é permitir, e a razão é operacional: um mapa
+  incompleto que nega por omissão derruba funcionalidade em produção toda vez que alguém adiciona
+  uma tool e esquece a linha.
+- **A poda preserva a ordem** da lista original. Ordem de tools é entrada do modelo; embaralhá-la
+  entre turnos introduz variância que ninguém pediu.
+
+Cobertura de referência no campo: 52 casos de teste **só** sobre o segundo estágio. Não é excesso —
+é o estágio em que um erro é invisível (a tool some, o modelo se adapta, e ninguém percebe até a
+reclamação).
+
+---
+
+## Exigir tool no turno
+
+Quando **toda** ação do agente é uma tool, um turno que não chama tool nenhuma é, por construção,
+um turno perdido.
+
+**`ChatToolMode.RequireAny` existe.** Medido por reflexão sobre
+`Microsoft.Extensions.AI.Abstractions` 10.9.0 em 2026-09-08: `ChatToolMode` expõe `Auto`, `None`,
+`RequireAny` (do tipo `RequiredChatToolMode`) e o método `RequireSpecific(string functionName)`. A
+restrição de uso é a esperada: é preciso haver ao menos uma tool em `ChatOptions.Tools`.
+
+**Este standard o recomenda como forma default para esse caso** — e para no ponto exato em que uma
+recomendação viraria prescrição cega.
+
+### A alternativa não é um defeito, e o critério de saída é parte da regra
+
+A alternativa medida em campo é a **segunda passada**: quando a primeira não chama tool, o código
+reenvia com uma mensagem fixa pedindo a ação. É fácil chamar isso de gambiarra; os fatos não
+sustentam:
+
+- Tem **7 testes dedicados**.
+- Tem um vocabulário fechado de **quatro desfechos**, incluindo `recovered` — ou seja, o caso "a
+  segunda passada salvou o turno" é **contado**, não suposto.
+- **Preserva o desfecho da primeira passada** quando a segunda falha no transporte, em vez de
+  transformar um erro de rede em "o agente não fez nada".
+- É chamado **no próprio código** de *"migração futura pendente de métrica"*.
+
+Transformar uma migração que o código deixou aberta de propósito numa regra é adiantar uma decisão
+que ninguém mediu. Então o standard escreve o **critério de saída**:
+
+> **Migre para `RequireAny` quando a taxa de `recovered` não pagar o custo da segunda chamada.** Os
+> dois números existem: a contagem de `recovered` sobre o total de turnos, e o custo por turno da
+> chamada extra (`ai-agents-cost-and-budget`). Se `recovered` é raro, a segunda passada é seguro
+> caro; se é frequente, ela está compensando um prompt fraco, e `RequireAny` vai expor isso como
+> erro em vez de escondê-lo como recuperação.
+
+**E o que se perde na migração**, para que a decisão seja informada: a recuperação best-effort
+desaparece (um turno que hoje se salva passa a falhar), e o **acumulador de uso que soma as duas
+passadas** perde a razão de existir — se ele for removido junto, a contabilidade de custo daquele
+turno muda de forma, o que precisa ser conferido antes e depois.
+
+---
+
+## Teto de tool calls e isenta
+
+Um agente que pode chamar tools em loop precisa de um teto, e o teto precisa de uma **isenta**.
+
+- **Teto por turno** — um número de voltas de tool calling. Referência de campo: 8.
+- **Uma tool isenta**, tipicamente a que fala com o interlocutor: com ela configurada, o loop tolera
+  N negações pós-teto antes de encerrar o turno. Sem isenta, bater o teto significa **o agente parar
+  de responder no meio**, que é o pior desfecho possível numa conversa.
+- **O valor efetivo vem da configuração**, por tenant ou por produto, não de uma constante.
+- Bater o teto é **evento observável**, não um `return` silencioso.
+
+Nota de camada: o teto de voltas é **nível de agente** (uma opção do pipeline de invocação de
+funções), não uma propriedade das opções de chamada. Confundir os dois faz o teto ser enviado ao
+provider, onde ele não significa nada.
+
+---
+
+## Agente auxiliar em sequência
+
+**Etapa fixa do turno roda em sequência, no código. Aninhar um agente numa tool call é decisão
+própria, com critério — não o default.**
+
+### A fronteira com `multi-agent-patterns`, escrita para não virar contradição
+
+`ai-agents-multi-agent-patterns` é o dono da composição entre agentes, e ele **recomenda**
+Agent-as-Tool (`agent.AsAIFunction()` — API real, medida no pin: `AIAgentExtensions.AsAIFunction`
+existe em `Microsoft.Agents.AI` 1.20.0), com teto de **≤ 2 níveis** de aninhamento. Isso **não**
+contradiz este arquivo, e a fronteira é uma pergunta só:
+
+| Pergunta | Resposta | Forma |
+|---|---|---|
+| **Quem decide se o auxiliar roda?** O **modelo**, turno a turno | Agent-as-Tool é o padrão: `AsAIFunction()`, ≤ 2 níveis (`ai-agents-multi-agent-patterns`) | aninhado, deliberadamente |
+| O **código** — é etapa fixa do turno, sempre acontece | **sequência no código**, nunca aninhada | o orquestrador é o código |
+
+O caso deste standard é quase sempre o segundo: numa conversa com fases, o auxiliar (persona,
+sumarização, extração) é **etapa fixa**, não escolha do modelo. Aninhá-lo paga o preço abaixo sem
+comprar a única coisa que o aninhamento oferece — deixar o modelo decidir.
+
+**O preço, concretamente:** o custo do agente interno aparece como custo de uma tool (logo, some da
+contabilidade por agente); o teto de tool calls do externo não governa o interno; o timeout do turno
+passa a cobrir duas chamadas de LLM em série; e o span do interno pendura-se sob `execute_tool`, onde
+nenhum painel de agente procura. Quando a decisão **é** do modelo, esses quatro custos continuam
+valendo — a diferença é que aí eles foram escolhidos, e o `decisions.md` diz por quê.
+
+Os dois lados de campo, e é raro ter os dois:
+
+| Lado | O que o acervo mostra |
+|---|---|
+| **Declarado** | Um projeto escreve o contrato explicitamente: *"nenhum agente chama outro; nesting é anti-padrão nomeado"* |
+| **Medido como problema** | Outro projeto roda um agente de persona **dentro** de uma tool call do agente principal — e a persona é etapa **fixa** daquele turno, isto é, o segundo caso da tabela acima |
+
+A composição legítima — quando ela é mesmo necessária — é assunto de
+`ai-agents-multi-agent-patterns`, e este standard não a repete: aponta.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Um agente por fase | A transição vira orquestração; o histórico fragmenta | Um agente, fase como dado do turno |
+| Fase derivada da memória do modelo | O modelo "esquece" a fase, e o bug não é reproduzível | Derive de estado observável, a cada turno |
+| Montagem de prompt em mais de um lugar | Regra nova entra em dois e esquece o terceiro | Um compositor, puro |
+| String de prompt guardada em cache ao lado dos blocos | A telemetria passa a poder mentir; o hash não prova nada | Derive sem cache, sempre |
+| Allow-list negando por omissão | Tool nova sem linha no mapa derruba funcionalidade em produção | Ausente do mapa = disponível |
+| Poda que reordena as tools | Variância de entrada que ninguém pediu | Preserve a ordem |
+| Teto de tool calls sem isenta | O agente para de responder no meio da conversa | Isenta configurada, com tolerância pós-teto |
+| Teto tratado como opção de chamada | Vai ao provider, onde não significa nada | É opção do pipeline, nível de agente |
+| `RequireAny` adotado sem medir `recovered` | Troca uma recuperação medida por uma falha nova | Aplique o critério de saída antes |
+| Etapa FIXA do turno aninhada numa tool call | Paga custo, teto, timeout e span quebrados sem comprar nada — ninguém precisava decidir | Sequência, no código |
+| Agent-as-Tool adotado sem registrar a decisão, ou além de 2 níveis | Os quatro custos viram surpresa, e o 3º nível é sinal de que devia ser sequência | Decisão no `decisions.md`, teto ≤ 2 níveis (`ai-agents-multi-agent-patterns`) |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Existe **um** compositor de turno, puro e sem I/O, e nenhuma segunda montagem de prompt
+- [ ] O prompt é composto de blocos nomeados, e o texto enviado é derivado sem cache
+- [ ] A fase é derivada de estado observável a cada turno
+- [ ] A allow-list poda por fase e por capacidade, nessa ordem, preservando a ordem das tools
+- [ ] Tool ausente do mapa de capacidade é tratada como **disponível**
+- [ ] Há teto de tool calls por turno, com tool isenta, e bater o teto é observável
+- [ ] O teto está no nível de agente, não nas opções de chamada
+- [ ] Se `RequireAny` foi adotado: a taxa de `recovered` e o custo da segunda chamada estão no
+      `decisions.md`. Se não foi: o critério de saída está escrito
+- [ ] Nenhuma etapa **fixa** do turno é invocada de dentro de uma tool call. Onde há aninhamento, quem decide é o **modelo**, está registrado no `decisions.md`, e respeita o teto de ≤ 2 níveis de `ai-agents-multi-agent-patterns`
+
+---
+
+## References
+
+- `ai-agents-agent-archetypes` — o catálogo das quatro formas; este é o aprofundamento da primeira
+- `ai-agents-multi-agent-patterns` — dono da composição entre agentes; a seção de auxiliar aponta
+  para lá em vez de duplicá-lo
+- `ai-agents-agent-spec` — o agente como dado, e a regra "nulo = não envia"
+- `ai-agents-observability-patterns` — a rastreabilidade que a invariante do compositor torna
+  confiável
+- `ai-agents-cost-and-budget` — o custo da segunda chamada, que é metade do critério de saída
+- `ai-agents-testing-ai` — como exercitar compositor, allow-list e teto sem rede
+
+> **Lacuna declarada, não escondida.** O par compilável deste standard seria um
+> `TurnPlanComposer` em `templates/dotnet/ai-kit/src/Morph.AiKit/Agents/`, com o teste de
+> concatenação sem cache em `tests/Morph.AiKit.Tests/`. **Ele ainda não existe** — nem no ai-kit
+> atual nem no plano que o construiu. Por isso o cabeçalho deste arquivo declara verificação
+> documental e **não** carimba `provado por`: prova inexistente é pior que prova ausente.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/conversational-agent-with-phases.md v1.0 (2026-09-08)*

package/framework/standards/ai-agents/cost-and-budget.md

@@ -0,0 +1,256 @@
+# Cost and Budget — tarifa, cálculo e teto de gasto de um agente
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** custo de llm, cost middleware, UsageCostMiddleware, teto de custo, budget middleware, tarifa por token, cost_usd, orçamento do agente
+> **Read by Claude in:** implement (ao registrar custo ou impor teto) e troubleshoot (fatura maior que o esperado, custo nulo no relatório)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Middleware/UsageCostMiddleware.cs`, `.../Middleware/UsageCostRecord.cs` e `.../Providers/ModelAlias.cs` — o middleware, o record de custo não-nulo e a conta de tarifa são o que o kit compila. A ausência de qualquer propriedade de preço em `UsageDetails` foi **medida por reflexão sobre `Microsoft.Extensions.AI.Abstractions` 10.9.0** em 2026-09-08. O teto de orçamento é **verificação documental** — o ai-kit não traz um middleware de orçamento. Last-verified: 2026-09-08.
+
+---
+
+## Tarifa no registry
+
+**O SDK dá tokens e não dá dinheiro.** Medido por reflexão sobre
+`Microsoft.Extensions.AI.Abstractions` 10.9.0 em 2026-09-08, `UsageDetails` expõe:
+
+`InputTokenCount` · `OutputTokenCount` · `TotalTokenCount` · `CachedInputTokenCount` ·
+`ReasoningTokenCount` · os pares de texto e áudio (`InputTextTokenCount`, `InputAudioTokenCount`,
+`OutputTextTokenCount`, `OutputAudioTokenCount`) · `AdditionalCounts` · e o método
+`Add(UsageDetails)`.
+
+**Nenhuma propriedade de preço.** Nem tarifa, nem moeda, nem custo. Isso não é lacuna do pacote: é a
+divisão certa. A tarifa muda por contrato, por região e por semana; um SDK que a embutisse estaria
+errado no dia seguinte.
+
+**Logo a tarifa é do projeto, e mora por alias no registry** — o mesmo lugar onde já moram provider,
+modelo e protocolo. A forma que o kit compila:
+
+| Campo | Significado |
+|---|---|
+| `InputPerMTok` | USD por 1M de tokens de entrada |
+| `OutputPerMTok` | USD por 1M de tokens de saída |
+| `CachedInputPerMTok` | USD por 1M de tokens de entrada servidos do cache. **Nulo = não há desconto declarado**, e então token cacheado é cobrado como entrada normal. Nulo **nunca** significa "de graça" |
+
+**E a tarifa precisa de data — que NÃO cabe no `pricing`.** Tarifa envelhece, e um preço sem data é
+um número que ninguém sabe se ainda vale. Mas o exemplar estampado acima **recusa** um campo de data:
+medido em 2026-09-08, `ModelRegistry` valida o objeto `pricing` contra uma allowlist fechada de
+exatamente três chaves (`inputPerMTok`, `outputPerMTok`, `cachedInputPerMTok`) e chama
+`RejectUnknownProperties` — qualquer quarta chave **derruba a carga do registry**. A allowlist do
+alias também não tem chave de data.
+
+Onde a data mora, então:
+
+| Opção | Custo |
+|---|---|
+| **Comentário JSONC no registry**, ao lado do bloco `pricing` | Zero: o parser do exemplar já roda com `JsonCommentHandling.Skip`, então o comentário é lido e descartado sem erro. É a opção default |
+| Campo novo na allowlist (`verifiedAt`) | Muda `.cs` — decisão de projeto, não deste standard |
+| Arquivo de procedência separado, versionado ao lado do registry | Serve quando a tarifa vem de contrato e precisa de histórico |
+
+**Nunca** escreva a data como uma quarta chave dentro de `pricing` sem antes abrir a allowlist: o
+registry para de carregar, e o sintoma (falha na inicialização) não aponta para a tarifa.
+
+**Alias sem tarifa precisa dizer por quê.** O registry do kit **recusa a carga** de um alias que não
+declare nem tarifa nem uma dispensa escrita (`pricingWaiver`) — modelo local, por exemplo, onde a
+conta é a máquina e não o token. O esquecimento deixou de ser um caminho possível: ou há tarifa, ou
+há motivo.
+
+---
+
+## O middleware de custo
+
+**Um middleware, não uma fórmula copiada.**
+
+A dor, literal e contada: num projeto do acervo a **mesma expressão de custo** aparece em **cinco
+call-sites, distribuídos em quatro arquivos** (um dos arquivos hospeda dois agentes). E o dado já
+era único — o diagnóstico do próprio projeto registra: *"o SDK expõe as contagens de token, mas não
+preços; a duplicação é do cálculo, não do dado"*.
+
+Duas cópias da mesma conta divergem. A divergência aparece na fatura, que é o pior lugar para
+descobri-la.
+
+A forma: um `DelegatingChatClient` que lê o `Usage` da resposta, chama **a** conta (a que já existe,
+no tipo de tarifa) e publica **uma linha por chamada** num sink de custo. O middleware não contém
+aritmética de tarifa — ele converte, chama e carimba.
+
+### Onde ele entra no pipeline, e por que a ordem não é estética
+
+O encaixe de custo fica **acima** da invocação de funções, com a telemetria de chat **abaixo** dela:
+
+```
+usage-cost  ->  function-invocation  ->  OpenTelemetry  ->  cliente do provider
+```
+
+O motivo é medido, não argumentado. **Acima** do cliente que invoca funções, o middleware vê **uma**
+resposta cujo `Usage` já traz o total de todas as voltas de tool, e publica **uma** linha por
+chamada. **Abaixo** dele, veria as respostas parciais — e leria o mesmo objeto de uso que o próprio
+cliente de invocação **muta** para acumular, o que faria a mesma conta dar resultado diferente
+conforme a hora de ler.
+
+---
+
+## Armadilhas de fórmula
+
+Três formas de errar a conta com todos os números certos:
+
+**(1) `ReasoningTokenCount` é cobrado como saída.** Uma fórmula que soma apenas entrada + saída sem
+conferir **como aquele provider bilha o raciocínio** subestima o custo de todo modelo de
+raciocínio — exatamente os mais caros.
+
+**(2) `CachedInputTokenCount` tem tarifa própria, e ignorá-lo superestima.** O detalhe que derruba
+implementações: **o cacheado é subconjunto da entrada**, não uma parcela a mais. Somar entrada +
+cacheado conta o mesmo token duas vezes. A conta correta separa a parte cacheada da parte cheia:
+
+```
+custo = (entrada - cacheado) * tarifaEntrada
+      + cacheado * (tarifaCache ?? tarifaEntrada)
+      + saida * tarifaSaida
+```
+
+E quando não há tarifa de cache declarada, **toda** a entrada é cobrada pela tarifa de entrada —
+nunca de graça.
+
+**(3) Taxa fixa por operação hospedada não aparece em `UsageDetails`.** Busca na web, interpretador
+de código e afins são cobrados por **operação**, não por token. Precedente de campo: um campo
+dedicado de custo de busca no registro de alias, com vinte linhas de comentário explicando que
+ignorá-lo subestimaria o teto. Se o agente usa uma dessas, a conta por token está estruturalmente
+incompleta, e o standard exige que isso seja declarado em vez de descoberto.
+
+---
+
+## cost_usd nunca nulo
+
+**`cost_usd` nunca é nulo.** Alias sem tarifa registra tokens e custo **zero com a ausência
+sinalizada** — nunca `null`, nunca um número inventado.
+
+Um custo nulo atravessa três camadas e vira um buraco no relatório, e ninguém consegue distinguir
+"não custou" de "não medimos". A distinção precisa viajar **junto** com o número, num estado
+explícito. Os três estados que o kit compila:
+
+| Estado | Significado | Pode somar numa fatura? |
+|---|---|---|
+| `Computed` | Tarifa do alias aplicada sobre uso reportado. O único em que o valor é **medição** | Sim, sem ressalva |
+| `Waived` | Alias sem tarifa **com dispensa escrita**. Zero por decisão registrada, e o motivo viaja junto | Sim, ciente de que é zero por decisão |
+| `UsageMissing` | O provider não reportou uso. Os tokens são desconhecidos, logo o custo também: o zero é **ausência de medição**, não gratuidade | Só com a ressalva explícita |
+
+**Precedente bom, do acervo:** um projeto trata uso nulo como zero com o comentário *"0 é o fallback
+honesto (custo subestimado, nunca inventado)"* — e persiste custo em **todos** os caminhos, inclusive
+nos de falha: um agente que devolve "não encontrado" devolve também *"o custo já pago visível"*.
+
+**Precedente ruim, e é regressão viva:** outro projeto grava `cost_usd = null` **hoje, em
+produção**, porque a tabela de preços sai vazia da configuração. O código está correto; a
+configuração está vazia; e o resultado é que o produto não sabe quanto gasta.
+
+---
+
+## Teto de orçamento
+
+**A unidade é parâmetro.** Por lead, por tenant, por operação, por dia — o standard não inventa uma
+"unidade de negócio" que nenhum projeto do acervo tem. O que ele fixa é a **forma** do teto.
+
+O acervo tem exatamente **um** teto duro (um limite de custo por lead) e ele revela uma dor de
+**lugar**, não de unidade: o teto mora **dentro de uma tool**, e por isso não vale para o pipeline
+inteiro. Tudo o que a tool não executa passa por fora dele. Os demais "tetos" do acervo são
+instrução textual ao modelo, chamados **no próprio código** de *"freio soft"* — o que é uma
+descrição honesta: o modelo não é um mecanismo de controle de gasto.
+
+**As quatro regras:**
+
+1. **O teto mora no pipeline, não dentro de uma tool.** Um teto que só uma tool respeita mede uma
+   fração do gasto.
+2. **Alerta antes de bloquear.** Um limiar de aviso, com a unidade e o valor acumulado, dá ao
+   operador a chance de agir; um bloqueio sem aviso prévio aparece como incidente.
+3. **O bloqueio devolve ao modelo uma frase acionável** — *"orçamento esgotado, conclua com o que
+   você já tem"* — e **nunca uma exceção**. Uma exceção no meio de um turno perde o trabalho já
+   pago; uma frase permite fechar a conversa com o que existe.
+4. **A unidade e o valor são configuração**, e o valor efetivo aparece no registro do turno, para
+   que "por que bloqueou" tenha resposta.
+
+> **Lacuna declarada.** O par compilável desta seção seria um `BudgetMiddleware` em
+> `templates/dotnet/ai-kit/src/Morph.AiKit/Middleware/`. **Ele não existe** — nem no ai-kit atual
+> nem no plano que o construiu. Por isso o cabeçalho declara esta parte como documental.
+
+---
+
+## Medir o total, não o piso
+
+**Um middleware no pipeline de chat mede o que passa pelo pipeline. O que não passa por ele precisa
+ser declarado.**
+
+O caso medido, e ele é o alerta inteiro: um projeto declara o contrato de *"no máximo 2 chamadas de
+LLM por turno"* — e a própria documentação do projeto reconhece que essa medição é **piso, não
+total**. Não são contadas: transcrição de áudio, visão (uma chamada por imagem e **uma por página**
+de PDF), embeddings de memória, embeddings de base de conhecimento, análise de memória e
+sumarização. Um turno com um PDF de três páginas chega a **cerca de nove** chamadas ao provider.
+
+A regra: faça o inventário das chamadas ao provider que **não** passam pelo pipeline instrumentado,
+e escreva-o. Um número que mede metade do gasto e se apresenta como total é pior que nenhum número,
+porque produz confiança.
+
+---
+
+## Fronteira com observability-patterns
+
+`ai-agents-observability-patterns` é o **dono canônico** de OpenTelemetry: setup, atributos de span,
+os nomes `gen_ai.*`, enrichment e a tabela de monitoramento. Ele continua sendo o lugar de "como
+instrumentar".
+
+**Este** standard é dono de: a **tarifa** (onde mora, com que forma, com que data), o **cálculo**
+(a conta, e as três armadilhas), o **estado** do custo (`Computed`/`Waived`/`UsageMissing`) e o
+**teto** de gasto.
+
+A delegação é **de mão dupla** e está escrita nos dois arquivos: quem chega pelo lado da
+observabilidade procurando tarifa é mandado para cá; quem chega aqui procurando atributo de span é
+mandado para lá. Nenhum dos dois duplica o outro.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Fórmula de custo copiada em cada agente | Duas cópias divergem, e a divergência aparece na fatura | Uma conta, num tipo; um middleware que a chama |
+| Tarifa embutida no código | Muda por contrato e por semana; vira literal errado | Tarifa por alias no registry |
+| Tarifa sem data de verificação | Ninguém sabe se o preço ainda vale | Data ao lado do valor — em comentário JSONC, não como quarta chave do `pricing` |
+| Alias sem tarifa e sem motivo escrito | O custo some em silêncio | Ou tarifa, ou dispensa escrita — o registry recusa o resto |
+| `cost_usd` nulo | Buraco no relatório; "não custou" e "não medimos" viram a mesma coisa | Zero com estado explícito |
+| Zero anônimo (sem estado) | Some a diferença entre dispensa e ausência de medição | `Computed` / `Waived` / `UsageMissing` |
+| Somar entrada + cacheado | Conta o mesmo token duas vezes: o cacheado é subconjunto | Separe a parte cheia da cacheada |
+| Ignorar `ReasoningTokenCount` | Subestima justamente os modelos mais caros | Confira como o provider bilha o raciocínio |
+| Ignorar taxa fixa de operação hospedada | A conta por token é estruturalmente incompleta | Declare a taxa, ou declare a incompletude |
+| Teto dentro de uma tool | Mede uma fração do gasto do pipeline | Teto no pipeline |
+| Teto como instrução textual ao modelo | O modelo não é mecanismo de controle de gasto | Código, com alerta antes do bloqueio |
+| Bloqueio por exceção | Perde o trabalho já pago no meio do turno | Frase acionável de volta ao modelo |
+| Contar só o que passa pelo pipeline e chamar de total | Produz confiança num número que mede metade | Inventário escrito do que não passa |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] A conta de custo existe em **um** lugar; nenhum agente a repete
+- [ ] A tarifa mora por alias no registry, e a **data** dela está registrada FORA do objeto `pricing` (comentário JSONC, campo próprio na allowlist, ou arquivo de procedência) — a allowlist do exemplar tem exatamente 3 chaves e recusa uma quarta
+- [ ] Nenhum alias sem tarifa e sem motivo escrito
+- [ ] O middleware de custo está **acima** da invocação de funções no pipeline
+- [ ] `cost_usd` nunca é nulo, e cada linha carrega o estado (`Computed`/`Waived`/`UsageMissing`)
+- [ ] A fórmula trata o cacheado como subconjunto da entrada
+- [ ] `ReasoningTokenCount` e taxas fixas de operação hospedada estão tratados ou declarados
+- [ ] Custo é persistido também nos caminhos de falha
+- [ ] Se há teto: ele está no pipeline, alerta antes de bloquear, e o bloqueio devolve frase, não exceção
+- [ ] Existe inventário escrito das chamadas ao provider que **não** passam pelo pipeline instrumentado
+
+---
+
+## References
+
+- `ai-agents-observability-patterns` — dono de OpenTelemetry, dos atributos `gen_ai.*` e da tabela
+  de monitoramento; a delegação de tarifa e teto é recíproca
+- `ai-agents-providers-model-registry` — Layer 0: o schema do documento onde a tarifa mora
+- `ai-agents-llm-runtime-defaults` — timeout, retry e o pin de SDK; a segunda chamada paga cujo custo
+  entra no critério de saída de `ai-agents-conversational-agent-with-phases`
+- `ai-agents-middleware-patterns` — o **mecanismo** de middleware de chat; este standard usa, não repete
+- `ai-agents-service-tier-flex` — reduzir tarifa em trabalho assíncrono
+- `ai-agents-batching` — reduzir tarifa processando N prompts em lote
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/cost-and-budget.md v1.0 (2026-09-08)*

package/framework/standards/ai-agents/durable-workflows-hitl.md

@@ -2,10 +2,10 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 1 (on-keyword)
-> **Keywords:** durable workflow, checkpoint, checkpointing, human in the loop, hitl, requestport, requestinfoevent, resume workflow, long running workflow, approval workflow, icheckpointstore, filesystemjsoncheckpointstore
-> **Read by Claude in:** plan (when `ai-agents-workflows` identifies a genuine HITL or long-running need) + implement (wiring `RequestPort` / `CheckpointManager`)
+> **Keywords:** durable workflow, checkpoint, checkpointing, human in the loop, hitl, requestport, requestinfoevent, resume workflow, long running workflow, approval workflow, icheckpointstore, filesystemjsoncheckpointstore, tool approval, ApprovalRequiredAIFunction, ToolApprovalAgent
+> **Read by Claude in:** plan (when `ai-agents-workflows` identifies a genuine HITL or long-running need, **or** when a single agent has an irreversible tool) + implement (wiring `RequestPort` / `CheckpointManager` / `ApprovalRequiredAIFunction`)
 
-**Verified against:** Microsoft.Agents.AI 1.0 GA (`Microsoft.Agents.AI.Workflows` namespace) + Microsoft.Agents.AI.DurableTask (prerelease, Azure-coupled — documented as an escape hatch, not adopted as default). Last-verified: 2026-07-06.
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08); `Microsoft.Agents.AI.Workflows` 1.20.0 e `Microsoft.Agents.AI.DurableTask` `1.16.0-preview.260730.1` **não estão no pin** — versões apuradas no nuget.org em 2026-09-08. **Verificação documental**, sem cláusula `provado por`: o ai-kit não exercita workflows nem aprovação de tool. Os nomes de tipo e membros de aprovação foram **medidos por reflexão sobre as assemblies do pin** em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -64,6 +64,87 @@ await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 
 ---
 
+## Aprovação de tool SEM workflow — o caso do agente único
+
+**A fronteira, primeiro.** Aprovação de tool e `RequestPort` não são o mesmo mecanismo, e usar o segundo onde bastava o primeiro é montar um grafo para pausar uma chamada:
+
+| Situação | Mecanismo |
+|---|---|
+| **Um agente**, uma tool de efeito irreversível (cobrar, enviar proposta, apagar) | `ApprovalRequiredAIFunction` — **sem workflow nenhum** |
+| Um grafo com etapa humana entre executores, ou espera de dias | `RequestPort` + `CheckpointManager` |
+
+O caso do agente único é o que a casa realmente tem (MORPH_OS: billing, envio de proposta) e é o que faltava neste standard.
+
+### O ciclo, medido em `Microsoft.Extensions.AI` 10.9.0
+
+```csharp
+// 1. Embrulhe a tool. ApprovalRequiredAIFunction : DelegatingAIFunction.
+AIFunction charge = AIFunctionFactory.Create(BillingTools.ChargeCustomer);
+AITool guarded = new ApprovalRequiredAIFunction(charge);
+
+AIAgent agent = registry.GetChatClient("text-default")
+    .AsAIAgent(instructions: "…", tools: [guarded]);
+
+AgentSession session = await agent.CreateSessionAsync();
+AgentResponse response = await agent.RunAsync("Cobre o cliente 42.", session);
+
+// 2. O run TERMINA pedindo aprovação — não bloqueia, não espera.
+//    ToolApprovalRequestContent.ToolCall é um ToolCallContent (medido; NÃO é
+//    FunctionCallContent — este último aparece em ToolAutoApprovalRuleContext).
+var pending = response.Messages
+    .SelectMany(m => m.Contents)
+    .OfType<ToolApprovalRequestContent>()
+    .ToList();
+
+// 3. Responda NA MESMA SESSÃO. CreateResponse(bool approved, string? reason).
+if (pending.Count > 0)
+{
+    var approvals = pending.Select(r => (AIContent)r.CreateResponse(approved: true, reason: "aprovado por lucas@…"));
+    response = await agent.RunAsync(new ChatMessage(ChatRole.User, [.. approvals]), session);
+}
+
+// 4. REPITA o passo 2 até não restar pendência. Uma volta pode pedir OUTRA tool.
+```
+
+**Os quatro pontos que erram na primeira tentativa:**
+
+1. **O run termina, não bloqueia.** Quem espera um `await` que "pausa" escreve um laço que nunca roda.
+2. **A resposta vai na MESMA sessão.** Sessão nova = a aprovação não casa com pedido nenhum.
+3. **Checar pendência depois de *cada* run**, num laço — não uma vez.
+4. **`ToolCall` é `ToolCallContent`.** Tipar como `FunctionCallContent` não compila.
+
+### `ToolApprovalAgent` — quando as regras se repetem
+
+Estável desde **1.14** (2026-07-21). Envolve o agente e centraliza a fila de pedidos e as regras de "sempre aprovar":
+
+```csharp
+AIAgent approving = agent.AsBuilder()
+    .UseToolApproval(new ToolApprovalAgentOptions
+    {
+        AutoApprovalRules = [ctx => ctx.FunctionCallContent.Name is "GetInvoice" or "ListPlans"],
+        MaxAutoApprovalIterations = 10,
+    })
+    .Build();
+```
+
+`ToolAutoApprovalRuleContext` entrega `Agent`, `Session`, `FunctionCallContent`, `RequestMessages` e `RunOptions` — a regra decide com o contexto inteiro, não só com o nome. `ToolApprovalAgent.AllToolsAutoApprovalRule` é o atalho "aprove tudo" (use em teste, não em produção). Para uma aprovação que vale para as próximas chamadas iguais, `ToolApprovalRequestContentExtensions.CreateAlwaysApproveToolResponse(...)` / `CreateAlwaysApproveToolWithArgumentsResponse(...)`.
+
+### Mudança de 1.14 que QUEBRA código
+
+A partir da 1.14 as respostas de aprovação passaram a ser **vinculadas ao request** — a reconciliação deixou de ser "qualquer resposta serve para qualquer pedido pendente". Código escrito contra a 1.0 precisa ser **revisto**, não apenas recompilado.
+
+O rastro disso está na própria API do pin: `ChatClientAgentOptions` expõe `DisableApprovalResponseBinding` (medido em 1.20.0) — uma flag que só existe porque o *binding* passou a ser o comportamento padrão. Ligá-la é voltar ao comportamento antigo, conscientemente.
+
+> **Nota de migração (histórico, não API viva):** `FunctionApprovalRequestContent` / `FunctionApprovalResponseContent` → `ToolApprovalRequestContent` / `ToolApprovalResponseContent`, renomeados no RC5 (2026-04-01), antes do GA. Os nomes antigos não existem no pin.
+
+### Quando aprovar — e quando aprovação não é a proteção certa
+
+**Peça aprovação quando a tool tem:** efeito colateral externo (cobrança, e-mail, contrato, deploy), dado sensível na saída, efeito **irreversível**, ou escopo amplo (apagar em lote, alterar preço).
+
+**E quando NÃO serve:** no turno de WhatsApp **o lead não é o aprovador**. Mandar um `ToolApprovalRequestContent` para quem está do outro lado da conversa é pedir ao interessado que autorize a si mesmo. Ali a proteção é **guard determinístico no choke-point** — a tool checa o estado do funil, o limite de valor e a permissão do operador **em código**, antes de agir, e recusa com motivo. Aprovação humana é para quando existe um humano com autoridade **diferente** da de quem falou.
+
+---
+
 ## Checkpointing — durável sem depender de Azure
 
 Checkpointing is part of the **base, GA** `Microsoft.Agents.AI.Workflows` namespace — no extra/preview package required. A checkpoint captures the full workflow state at each superstep boundary: executor state, pending messages, and pending `RequestPort` requests (so a pending approval survives a restore).
@@ -147,6 +228,8 @@ public sealed class PostgresCheckpointStore(NpgsqlDataSource dataSource) : IChec
 
 ## Azure Durable Task extension — escape hatch, not default
 
+> **Mudança estrutural na 1.17:** a integração Durable Task / Azure Functions foi **extraída para um repositório separado** — deixou de acompanhar o ciclo de release do `Microsoft.Agents.AI`. Isso se vê no próprio versionamento: em 2026-09-08 a última versão de `Microsoft.Agents.AI.DurableTask` no nuget.org é **`1.16.0-preview.260730.1`**, enquanto o pacote base já está em 1.20.0 — quatro minors atrás, e ainda preview. A conclusão desta seção **não muda**: não adotar por padrão. O motivo ganhou um segundo pé: além do acoplamento com Azure, a extensão agora **não é atualizada junto** com o framework.
+
 `Microsoft.Agents.AI.DurableTask` (prerelease) adds durability backed by the **Azure Durable Task Scheduler**, including cost-efficient multi-day HITL waits with zero compute cost while paused. Even its "bring-your-own-compute / self-hosted" mode still requires a Durable Task Scheduler backend (`Microsoft.DurableTask.*.AzureManaged` packages) — self-hosted means your own worker process, not an Azure-free backend.
 
 This framework deploys to VPS/Coolify by default and does not adopt Azure as a default dependency (see `ai-agents-setup` §3.4 on Azure OpenAI). For that reason, `Microsoft.Agents.AI.DurableTask` is **not adopted as default** here. The `CheckpointManager` + custom `ICheckpointStore` pattern above covers the same durability need without an Azure dependency. Only reach for the Durable Task extension when a specific client already runs on Azure and needs multi-day/serverless HITL waits — record that decision in `decisions.md`.
@@ -161,6 +244,11 @@ This framework deploys to VPS/Coolify by default and does not adopt Azure as a d
 | Reaching for `Microsoft.Agents.AI.DurableTask` by default | Adds an Azure Durable Task Scheduler dependency this framework's VPS-first stack doesn't otherwise need | Use base `CheckpointManager` + custom `ICheckpointStore`; reserve the Durable Task extension for projects already committed to Azure |
 | Storing checkpoints in a public or unauthenticated location | Checkpoint storage is a trust boundary — a tampered checkpoint can inject arbitrary state on restore | Restrict read/write access to the checkpoint store the same way you would a secrets store |
 | Skipping `OnCheckpointingAsync`/`OnCheckpointRestoredAsync` on an executor with instance state | State silently resets to defaults after a resume, corrupting workflow logic | Any executor with fields beyond the message flow must implement both methods |
+| **Montar um `Workflow` só para pausar uma tool de um agente único** | Um grafo inteiro, com checkpoint store, para o que `ApprovalRequiredAIFunction` resolve em duas linhas | `ApprovalRequiredAIFunction` — §Aprovação de tool SEM workflow |
+| **Responder a aprovação numa sessão nova** | A resposta não casa com o pedido; o run recomeça pedindo de novo | Mesma `AgentSession` |
+| **Checar `ToolApprovalRequestContent` uma vez só** | Uma volta aprovada pode pedir OUTRA tool; a segunda pendência passa despercebida | Laço: checar depois de **cada** run até zerar |
+| **Pedir aprovação ao lead no turno de WhatsApp** | O interessado autorizando a si mesmo não é controle nenhum | Guard determinístico no choke-point da tool |
+| Subir de 1.0 para ≥1.14 sem revisar a reconciliação de aprovações | Desde a 1.14 a resposta é **vinculada ao request**; o código antigo casa errado | Revisar; `DisableApprovalResponseBinding` é opt-out consciente, não default |
 
 ---
 
@@ -171,7 +259,11 @@ This framework deploys to VPS/Coolify by default and does not adopt Azure as a d
 - [ ] A `CheckpointManager` is wired whenever the workflow can pause across a process restart — `CreateInMemory()` is acceptable only for tests/demos.
 - [ ] If a custom `ICheckpointStore` was implemented, it persists to infrastructure already owned by the project (e.g., Neon Postgres), not a new ad hoc store.
 - [ ] Executors with instance state implement `OnCheckpointingAsync` and `OnCheckpointRestoredAsync`.
-- [ ] `Microsoft.Agents.AI.DurableTask` is present only if the project already runs on Azure and the choice is recorded in `decisions.md`.
+- [ ] `Microsoft.Agents.AI.DurableTask` is present only if the project already runs on Azure and the choice is recorded in `decisions.md` — ciente de que, desde a 1.17, o pacote vive em repositório separado e ficou para trás do framework.
+- [ ] Toda tool com efeito irreversível está embrulhada em `ApprovalRequiredAIFunction` **ou** tem um guard determinístico documentado — e a escolha entre os dois está escrita.
+- [ ] A resposta de aprovação é enviada na **mesma** `AgentSession`, num laço que checa pendências depois de cada run.
+- [ ] Nenhum `Workflow` foi criado apenas para pausar uma tool de um agente único.
+- [ ] Nenhuma ocorrência de `FunctionApprovalRequestContent` / `FunctionApprovalResponseContent` (nomes pré-GA).
 
 ---
 
@@ -185,7 +277,8 @@ This framework deploys to VPS/Coolify by default and does not adopt Azure as a d
 - Human-in-the-loop (HITL) | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/workflows/human-in-the-loop
 - Checkpoints | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/workflows/checkpoints
 - Durable Extension | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/integrations/durable-extension
+- Release notes 1.14 (2026-07-21) e 1.17 do `microsoft/agent-framework` — graduação do `ToolApprovalAgent` e extração do Durable Task (compilados em `docs/specs/elevacao-9/brutos/research-maf.md:312-331`, lidos 2026-09-07)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/durable-workflows-hitl.md v1.0 (2026-07-06)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/durable-workflows-hitl.md v2.0 (2026-09-08)*