senado-br-mcp 3.9.0 → 3.11.0

package/README.md

@@ -8,6 +8,7 @@
 [![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-senado-br-mcp-cloudflare)](https://lobehub.com/mcp/sidneybissoli-senado-br-mcp-cloudflare)
 [![LightNow capabilities](https://lightnow.ai/badge/io.github.SidneyBissoli/senado-br-mcp-cloudflare)](https://lightnow.ai/servers/io.github.SidneyBissoli/senado-br-mcp-cloudflare)
 [![senado-br-mcp-cloudflare MCP server](https://glama.ai/mcp/servers/SidneyBissoli/senado-br-mcp-cloudflare/badges/score.svg)](https://glama.ai/mcp/servers/SidneyBissoli/senado-br-mcp-cloudflare)
+[![smithery badge](https://smithery.ai/badge/sidneybissoli/senado-br-mcp-cloudflare)](https://smithery.ai/servers/sidneybissoli/senado-br-mcp-cloudflare)
 [![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/senado-br-mcp-cloudflare?style=flat&logo=github)](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)
 [![License: MIT](https://img.shields.io/github/license/SidneyBissoli/senado-br-mcp-cloudflare)](LICENSE)
@@ -153,7 +154,7 @@ Claude Code auto-discovers it when you work in this repo. To use it elsewhere, c
 - **Caching:** 2-layer (L0 memory + L1 Cache API) with SHA-256 keying
 - **e-Cidadania store:** D1 database refreshed by a Cron Trigger (every 2h) — list tools read from D1 with a live-scrape fallback and a staleness flag; detail tools stay live with write-through (see [e-Cidadania](#e-cidadania-d1-backed-cron-refreshed))
 - **Rate limiting:** Token bucket — global (8 req/s) + per-client (2 req/s)
-- **Upstream throttle:** Max 6 concurrent requests, 10s timeout, retry with exponential backoff
+- **Upstream throttle:** Max 6 concurrent requests, 10s budget per trip, retry on 429/5xx/network with exponential backoff and `Retry-After` (portfolio shared fetch `@sbissoli/mcp-upstream`); every response's provenance carries the measured `retrieval` diagnostics (trips, attempts, anomalies)
 - **Auth:** Optional Bearer token (set the `API_KEY` secret; open access when unset). Constant-time comparison.
 - **Observability:** Structured JSON logging + in-memory counters at `/metrics`; per-tool call telemetry (selection, error rate, cache-vs-live) in Cloudflare Analytics Engine, PII-free
 - **Liveness:** Runs on Cloudflare's own global network behind a custom domain — no third-party host that can go dark. Public `/health` and `/status` (version + last-deploy id/timestamp) make uptime and the current build verifiable; the **status** badge above pings the live endpoint

package/dist/call-shape.js

@@ -37,6 +37,13 @@
  */
 export function classifyError(message) {
     const m = message.toLowerCase();
+    // PRIMEIRO de todos, e de propósito: a rota que não existe na fonte é
+    // defeito NOSSO (montamos um caminho errado), e a palavra que a nomeia —
+    // "inexistente" — cairia em `nao_encontrado` logo abaixo, que é exatamente a
+    // conflação que o conserto de 24/09/2026 desfez na borda da rede. A frase
+    // vem de `MSG_ROTA_INEXISTENTE`; ela não é vocabulário da fonte, é nosso.
+    if (m.includes("defeito do servidor mcp"))
+        return "defeito";
     // A fronteira de palavra vai só no INÍCIO. Os padrões são RADICAIS
     // ("vazi", "obrigatóri", "indisponív") justamente porque a flexão muda o
     // fim: `\bvazi\b` não casa "vazia", e foi assim que "Resposta upstream
@@ -166,3 +173,43 @@ export function classifyThrown(error) {
     }
     return classifyError(error instanceof Error ? error.message : String(error));
 }
+/**
+ * Classe de um erro JSON-RPC do PROTOCOLO, pelo código antes da mensagem.
+ *
+ * POR QUE ELE CHEGA AQUI AGORA. Até 24/09/2026 este arquivo só era chamado de
+ * dentro do handler, com a exceção da tool na mão — e o cabeçalho acima ainda
+ * registra o limite daquele desenho: *erro de validação de esquema NÃO chega a
+ * esta camada; o SDK o responde antes do handler, e a chamada não é contada nem
+ * como chamada nem como erro*. Era verdade, e era o defeito: a recusa de esquema
+ * não gerava linha NENHUMA de telemetria. Medido na produção em 24/09/2026 pela
+ * rota do dono, ela sai como HTTP **200** com `result.isError: true` e sem
+ * código JSON-RPC; e ferramenta inexistente sai como **200** com o código
+ * **−32602** (não −32601, como se supunha). Desde então a telemetria lê o
+ * ENVELOPE da resposta (src/envelope.ts) e estes casos passam a existir.
+ *
+ * Os códigos reservados pela especificação JSON-RPC 2.0 dizem, sem ambiguidade
+ * de idioma, de quem é o conserto:
+ *
+ *  - −32700 parse error, −32600 invalid request, −32601 method not found e
+ *    −32602 invalid params são o CHAMADOR mandando algo que o protocolo
+ *    recusa. É `contrato` — e o painel exclui `contrato` da taxa de erro
+ *    (`eh_recusa_de_contrato()`), porque ferramenta que recusa chamada
+ *    malformada está funcionando;
+ *  - −32603 internal error é erro NOSSO, que escapou. É `defeito`, e por
+ *    decisão do dono em 24/09/2026 ele entra na fila de saúde do painel: sem
+ *    isso passaríamos a medir e continuaríamos a não agir.
+ *
+ * Código fora dessa faixa (erro definido pelo servidor, −32000 e abaixo) cai
+ * na mensagem, que é o caminho de `classifyError`.
+ *
+ * Cópia FIEL de sih-br-mcp/worker/src/call-shape.ts, onde a função estreou:
+ * classe medida por servidor com classificador diferente não é comparável, e
+ * comparar os sete é a razão de existir da seção de saúde do painel.
+ */
+export function classeDoErroRpc(code, message) {
+    if (code === -32700 || code === -32600 || code === -32601 || code === -32602)
+        return "contrato";
+    if (code === -32603)
+        return "defeito";
+    return classifyError(message);
+}

package/dist/envelope.js

@@ -0,0 +1,257 @@
+/**
+ * Leitura do ENVELOPE da resposta — o que transforma "o container devolveu
+ * HTTP 200" em "esta mensagem deu certo / esta falhou, e por quê".
+ *
+ * O PROBLEMA QUE ESTE ARQUIVO RESOLVE, E QUE AQUI É PIOR QUE NO `sih`. A
+ * telemetria deste Worker decide o desfecho pelo HTTP da resposta, e em cima
+ * disso `protocolNamesFromBody` (em src/instrument.ts) tinha a linha `if (status < 400) continue`, com
+ * o comentário "o hook de tools já gravou esta". A reconciliação era por STATUS,
+ * e supunha que 200 implica que o hook gravou. Quando a tool NÃO CHEGA A RODAR
+ * — recusa de esquema do zod, antes do handler — ninguém grava, e o `continue`
+ * fecha a única outra porta. O `sih` carimbava `ok` numa falha: número errado.
+ * Aqui não havia número NENHUM: a chamada não era contada nem como chamada.
+ *
+ * Medido na produção em 24/09/2026, pela rota do dono, no ilo, uis, senado e
+ * bcb — os quatro idênticos, e são DUAS formas, não uma: recusa de esquema sai
+ * HTTP 200 com `result.isError: true` e SEM código JSON-RPC; ferramenta
+ * inexistente sai HTTP 200 com o código −32602 (não −32601). Os dois são 200,
+ * então os dois caíam no `continue`.
+ *
+ * POR QUE NÃO BUFFERIZAR. Este Worker não é proxy — quem produz a resposta é o
+ * `createMcpHandler` aqui dentro —, mas a técnica é a mesma e pelo mesmo motivo:
+ * segurar bytes para ler o fim trocaria um defeito de medição por um defeito de
+ * produto (a lição do `sih`, cuja série de 34 anos leva ~30 s). O corpo é TEADO
+ * (`ReadableStream.tee()`): um ramo segue intocado para o cliente, no mesmo
+ * ritmo de antes, e o outro é lido aqui em `ctx.waitUntil`, depois que a
+ * resposta já saiu.
+ *
+ * O TEE RESOLVE, DE QUEBRA, UM PROBLEMA DE TEMPO. O hook de tools escreve
+ * durante a execução da tool, que num transporte SSE pode terminar DEPOIS de o
+ * handler já ter devolvido a Response. Ler o envelope até o fim do stream é,
+ * por construção, esperar a tool acabar — é só então que se sabe o que o hook
+ * gravou, e a reconciliação por nome (src/instrument.ts) só vale aí.
+ *
+ * REGRA DE OURO DESTE MÓDULO: ele nunca lança e nunca segura bytes. Qualquer
+ * coisa que ele não entenda vira "sem desfecho", e quem chama cai no critério
+ * antigo (o HTTP). Medir pior é aceitável; atrapalhar a resposta do usuário não é.
+ *
+ * DOIS TETOS, pelo mesmo motivo. Um evento SSE acumulado passa de
+ * `MAX_EVENTO_BYTES` → é descartado sem parsear (o `isError` pode estar no fim
+ * do JSON, mas mensagem de erro é curta: evento gigante é quase certamente
+ * resultado feliz, e o teto troca uma classificação improvável por um limite de
+ * memória e de CPU garantido). Mais de `MAX_DESFECHOS` respostas no mesmo corpo
+ * → o resto é ignorado; lote JSON-RPC de verdade tem punhado de mensagens.
+ *
+ * O CAMINHO DE ERRO-MOLE FICA DE FORA, de propósito. Ferramenta que responde
+ * ausência como DADO — uma resposta de SUCESSO cujo payload diz "não há" — está
+ * funcionando, e continua sendo `ok`. O que conta como falha é `isError: true`
+ * ou um erro JSON-RPC, nada mais. (No `sih`, de onde este arquivo vem, isso é a
+ * decisão 38 e seis ferramentas dependem dela; aqui o erro de tool já nasce de
+ * `IlostatUserError` / `IlostatUpstreamError` e vira `isError`.)
+ *
+ * Cópia de sih-br-mcp/worker/src/envelope.ts, porque o classificador não pode
+ * divergir entre os sete. O que muda é só este cabeçalho e o `teeResposta` do
+ * fim, que lá não existe: o `sih` monta a Response do zero a partir do upstream
+ * e teia no caminho; aqui a Response já vem pronta do handler.
+ */
+import { classeDoErroRpc, classifyError, errorText } from "./call-shape.js";
+/** Teto de bytes acumulados por evento SSE (ou por linha) antes de desistir dele. */
+export const MAX_EVENTO_BYTES = 64 * 1024;
+/** Teto de respostas rastreadas por corpo. */
+export const MAX_DESFECHOS = 64;
+/**
+ * Desfecho de uma resposta JSON-RPC, com o `id` que a liga ao pedido.
+ * `null` quando o objeto não é uma resposta identificável:
+ *  - sem `id` (ou `id: null`, que é a resposta a um pedido que nem parseou) —
+ *    não há a que ligar, e o chamador fica com o critério do HTTP;
+ *  - sem `result` e sem `error` — não é resposta (é notificação, ou lixo).
+ */
+export function desfechoDaResposta(msg) {
+    if (!msg || typeof msg !== "object" || Array.isArray(msg))
+        return null;
+    const m = msg;
+    if (typeof m.id !== "string" && typeof m.id !== "number")
+        return null;
+    const id = String(m.id);
+    if (m.error && typeof m.error === "object") {
+        const e = m.error;
+        const code = typeof e.code === "number" ? e.code : undefined;
+        const texto = typeof e.message === "string" ? e.message : "";
+        return { id, desfecho: { erro: true, classe: classeDoErroRpc(code, texto) } };
+    }
+    if (m.result && typeof m.result === "object") {
+        const r = m.result;
+        if (r.isError === true) {
+            return { id, desfecho: { erro: true, classe: classifyError(errorText(m.result)) } };
+        }
+        return { id, desfecho: { erro: false, classe: "" } };
+    }
+    // `result` primitivo (o SDK responde `{}` em alguns métodos, mas nunca um
+    // escalar) ainda é sucesso; o que não é resposta é o objeto sem os dois.
+    if (m.result !== undefined)
+        return { id, desfecho: { erro: false, classe: "" } };
+    return null;
+}
+/**
+ * O desfecho de UMA mensagem do pedido, já com o CRITÉRIO DE RESERVA aplicado.
+ *
+ * Regra: vale o que o envelope disse. Quando o envelope não disse nada — `id`
+ * ausente (notificação), stream cortado, evento grande demais, resposta que
+ * não parseou —, vale o HTTP do container, que era o critério único até
+ * 24/09/2026. Nunca se inventa classe: sem leitura, a classe é "".
+ */
+export function resolveDesfecho(id, desfechos, falhouHttp) {
+    const lido = id === "" ? undefined : desfechos.get(id);
+    return lido ?? { erro: falhouHttp, classe: "" };
+}
+/**
+ * Lê o corpo da resposta aos pedaços e vai colhendo desfechos por `id`.
+ *
+ * Aceita os dois formatos que o transporte Streamable HTTP usa: SSE (`data:`
+ * por evento, evento fechado por linha em branco, várias linhas `data:` do
+ * mesmo evento juntadas por `\n`) e JSON cru (resposta direta, sem stream).
+ * Linhas `event:`, `id:`, `retry:` e comentários (`:`) são ignoradas.
+ */
+export class LeitorDeEnvelope {
+    resto = "";
+    descartandoLinha = false;
+    evento = [];
+    bytesDoEvento = 0;
+    eventoEstourado = false;
+    viuSse = false;
+    cru = "";
+    /** Desfechos colhidos, por `id` de mensagem JSON-RPC. */
+    desfechos = new Map();
+    /** Entrega mais um pedaço de TEXTO já decodificado. Nunca lança. */
+    push(texto) {
+        if (!this.viuSse && this.cru.length < MAX_EVENTO_BYTES)
+            this.cru += texto;
+        this.resto += texto;
+        for (;;) {
+            const quebra = this.resto.indexOf("\n");
+            if (quebra < 0)
+                break;
+            const linha = this.resto.slice(0, quebra);
+            this.resto = this.resto.slice(quebra + 1);
+            if (this.descartandoLinha) {
+                // Fim da linha gigante que foi descartada: o evento inteiro cai junto,
+                // porque o JSON dele está incompleto.
+                this.descartandoLinha = false;
+                this.eventoEstourado = true;
+                continue;
+            }
+            this.linha(linha.endsWith("\r") ? linha.slice(0, -1) : linha);
+        }
+        // Linha sem fim à vista e já maior que o teto: para de acumular em vez de
+        // crescer com o corpo (uma resposta de 34 anos é uma única linha `data:`).
+        if (this.resto.length > MAX_EVENTO_BYTES) {
+            this.resto = "";
+            this.descartandoLinha = true;
+        }
+    }
+    /** Fecha o que ficou pendente. Chamar uma vez, ao fim do stream. */
+    end() {
+        if (this.resto !== "" && !this.descartandoLinha) {
+            const linha = this.resto.endsWith("\r") ? this.resto.slice(0, -1) : this.resto;
+            this.resto = "";
+            this.linha(linha);
+        }
+        this.fechaEvento();
+        // Corpo que nunca teve uma linha `data:` é JSON cru.
+        if (!this.viuSse)
+            this.registra(this.cru);
+    }
+    linha(linha) {
+        if (linha === "") {
+            this.fechaEvento();
+            return;
+        }
+        if (!linha.startsWith("data:"))
+            return;
+        this.viuSse = true;
+        const pedaco = linha.slice(5).replace(/^ /, "");
+        this.bytesDoEvento += pedaco.length;
+        if (this.bytesDoEvento > MAX_EVENTO_BYTES) {
+            this.eventoEstourado = true;
+            this.evento = [];
+            return;
+        }
+        this.evento.push(pedaco);
+    }
+    fechaEvento() {
+        const partes = this.evento;
+        const estourou = this.eventoEstourado;
+        this.evento = [];
+        this.bytesDoEvento = 0;
+        this.eventoEstourado = false;
+        if (estourou || partes.length === 0)
+            return;
+        this.registra(partes.join("\n"));
+    }
+    registra(json) {
+        if (json === "" || this.desfechos.size >= MAX_DESFECHOS)
+            return;
+        let obj;
+        try {
+            obj = JSON.parse(json);
+        }
+        catch {
+            return; // pedaço cortado ao meio, ou não era JSON: fica sem desfecho
+        }
+        for (const item of Array.isArray(obj) ? obj : [obj]) {
+            if (this.desfechos.size >= MAX_DESFECHOS)
+                return;
+            const d = desfechoDaResposta(item);
+            if (d)
+                this.desfechos.set(d.id, d.desfecho);
+        }
+    }
+}
+/**
+ * Consome um stream inteiro e devolve os desfechos por `id`. Nunca lança: se o
+ * stream for cortado no meio (cliente desconectou, container caiu), vale o que
+ * deu para ler até ali e o resto fica sem desfecho.
+ */
+export async function desfechosDoCorpo(corpo) {
+    const leitor = new LeitorDeEnvelope();
+    const decoder = new TextDecoder();
+    const reader = corpo.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                leitor.push(decoder.decode(value, { stream: true }));
+        }
+        leitor.push(decoder.decode());
+    }
+    catch {
+        // Stream interrompido: o que já foi lido continua valendo.
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // ignorado
+        }
+    }
+    leitor.end();
+    return leitor.desfechos;
+}
+/**
+ * Parte o corpo da resposta em dois: o que vai para o cliente e o que a
+ * telemetria lê. Só isto, e nunca mais que isto — a Response devolvida tem o
+ * mesmo status, o mesmo statusText e os mesmos cabeçalhos da original.
+ *
+ * Resposta sem corpo (204, HEAD, erro montado na borda) devolve `corpo: null` e
+ * a própria Response intacta: não há o que teiar, e `new Response(null, resp)`
+ * seria uma cópia à toa.
+ */
+export function teeResposta(resposta) {
+    if (!resposta.body)
+        return { paraCliente: resposta, paraLeitura: null };
+    const [cliente, leitura] = resposta.body.tee();
+    return { paraCliente: new Response(cliente, resposta), paraLeitura: leitura };
+}

package/dist/instrument.js

@@ -28,9 +28,11 @@
  * connector is only identifiable via the secret header his MCP clients send
  * (SELF_HEADER, value = the SELF_MARKER Wrangler secret).
  */
+import { resolveDesfecho } from "./envelope.js";
 import { classifyError, classifyThrown, errorText, paramNames } from "./call-shape.js";
 import { incr, incrTool } from "./metrics.js";
 import { callCache, cacheClass } from "./observability/call-context.js";
+import { withUpstreamCall } from "./throttle/upstream.js";
 /** Header the owner's MCP clients send (value = the SELF_MARKER secret). */
 export const SELF_HEADER = "x-mcp-self";
 /**
@@ -62,7 +64,7 @@ export function tagRequest(request, selfSecret, sessao = "") {
         sessao,
     };
 }
-export function instrumentTool(name, cb, analytics, tag) {
+export function instrumentTool(name, cb, analytics, tag, gravados) {
     return async (...args) => {
         incr("toolCalls");
         let isError = false;
@@ -70,7 +72,12 @@ export function instrumentTool(name, cb, analytics, tag) {
         // Per-call store the cache layer increments per upstream fetch (see call-context.ts).
         const stats = { fetches: 0, hits: 0 };
         try {
-            const result = await callCache.run(stats, () => cb(...args));
+            // Dois contextos por chamada, aninhados: o coletor de REDE do fetch comum
+            // (idas, tentativas, anomalias → `retrieval` da proveniência; ver
+            // src/throttle/upstream.ts) e o acumulador de CACHE (acertos → blob3).
+            // Este é o único lugar em que uma chamada de tool começa — stdio e Worker
+            // passam pelo mesmo funil (`host.tool` em src/server.ts).
+            const result = await withUpstreamCall(() => callCache.run(stats, () => Promise.resolve(cb(...args))));
             isError =
                 typeof result === "object" && result !== null && result.isError === true;
             if (isError)
@@ -93,6 +100,12 @@ export function instrumentTool(name, cb, analytics, tag) {
             // chamada nem como erro. Medido em 10/09/2026 pelo /metrics: três
             // chamadas com argumento de forma errada não moveram o contador.
             recordToolCall(name, isError, stats, analytics, tag, classe, paramNames(args));
+            // Recibo desta requisicao: e contra ele que recordProtocolMethods
+            // reconcilia. Fica no `finally` junto da gravacao, para os dois nunca
+            // discordarem. A recusa de esquema NAO passa por aqui -- e exatamente
+            // por isso que ela nao deixa recibo, e a linha dela e escrita la.
+            if (gravados)
+                gravados.set(name, (gravados.get(name) ?? 0) + 1);
         }
     };
 }
@@ -135,71 +148,52 @@ function recordToolCall(name, isError, stats, analytics, tag, errorClass = "", p
     }
 }
 /**
- * Métodos de PROTOCOLO, gravados na camada HTTP.
+ * As mensagens do corpo que ainda precisam de linha, já descontado o recibo.
  *
- * `instrumentTool` só vê `tools/call`: ela envolve o callback da tool.
- * `initialize`, `tools/list`, `notifications/*`, `ping` e o que mais o
- * cliente mande (`server/discover`, por exemplo) atravessam o transporte sem
- * tocar tool nenhuma — e são eles que contam o FUNIL DE SESSÃO: quantos
- * `initialize` viram chamada de ferramenta de verdade, que é o que separa
- * "acharam o servidor" de "usaram o servidor". Medido em 2026-09-10: só o
- * sih-br-mcp os gravava, porque lá o Worker é um proxy que lê o corpo
- * JSON-RPC antes de encaminhar. Aqui o servidor roda dentro do Worker, e o
- * corpo vem de uma CÓPIA tirada antes de o handler consumir o stream
- * (src/index.ts). Desde 2026-09-16 a frota inteira grava igual.
- *
- * Mesmo esquema de blobs, com o método no lugar do nome da tool — igual ao
- * sih. O painel separa os dois pelo nome (`metodo_de_protocolo`). Classe de
- * cache, classe de erro e parâmetros ficam vazios; fetches e hits, zero.
- *
- * O que entra, e de onde vem o desfecho:
- *  - todo método que não é `tools/call` → uma linha, "ok" se o HTTP da
- *    resposta for < 400, "error" senão. LIMITAÇÃO, a mesma do sih: erro
- *    JSON-RPC que viaja dentro de um 200 (método desconhecido, -32601) sai
- *    como "ok" — ler exigiria consumir o corpo que está sendo devolvido;
- *  - `tools/call` só quando o HTTP é ≥ 400: o transporte recusou antes de
- *    despachar (Accept errado, sessão inválida, Origin estrangeiro) e a tool
- *    nunca rodou; sem isto a recusa seria invisível. Com HTTP < 400 a
- *    `instrumentTool` já gravou a linha, com o desfecho de verdade — não se
- *    grava de novo;
- *  - lote JSON-RPC (array) → uma linha por item; item sem `method` (resposta
- *    do cliente, corpo que não é JSON) → nada.
- *
- * Só no Analytics Engine: os contadores do /metrics continuam contando tools.
+ * `gravados` é CONSUMIDO (decrementado) durante a varredura. Chamar sem ele
+ * significa "a instrumentTool não gravou nada".
  */
-export function protocolNamesFromBody(body, status) {
+export function protocolMessagesFromBody(body, gravados) {
     const itens = Array.isArray(body) ? body : [body];
-    const nomes = [];
+    const mensagens = [];
     for (const item of itens) {
         if (!item || typeof item !== "object")
             continue;
         const msg = item;
         if (typeof msg.method !== "string" || msg.method === "")
             continue;
+        const id = typeof msg.id === "string" || typeof msg.id === "number" ? String(msg.id) : "";
         if (msg.method === "tools/call") {
-            if (status < 400)
-                continue; // instrumentTool já gravou esta
             const params = msg.params;
-            nomes.push(typeof params?.name === "string" && params.name !== "" ? params.name : "tools/call");
+            const nome = typeof params?.name === "string" && params.name !== "" ? params.name : "tools/call";
+            const recibo = gravados?.get(nome) ?? 0;
+            if (recibo > 0) {
+                gravados?.set(nome, recibo - 1); // a instrumentTool já gravou esta
+                continue;
+            }
+            mensagens.push({ nome, id });
         }
         else {
-            nomes.push(msg.method);
+            mensagens.push({ nome: msg.method, id });
         }
     }
-    return nomes;
+    return mensagens;
 }
 /**
  * Grava no Analytics Engine os métodos de protocolo de um POST no endpoint
- * MCP (ver protocolNamesFromBody). Devolve os nomes gravados. Sem binding,
- * não grava nada.
+ * MCP (ver acima). Devolve os nomes gravados. Sem binding, não grava nada.
+ *
+ * `desfechos` é o que a leitura do envelope colheu por `id`; sem ele — corpo
+ * não teado, stream cortado — vale o HTTP, que é o critério de reserva.
  */
-export function recordProtocolMethods(analytics, tag, body, status) {
+export function recordProtocolMethods(analytics, tag, body, status, desfechos = new Map(), gravados) {
     if (!analytics || body === undefined)
         return [];
     const cliente = clientNameFromBody(body);
-    const nomes = protocolNamesFromBody(body, status);
-    const isError = status >= 400;
-    for (const name of nomes) {
+    const mensagens = protocolMessagesFromBody(body, gravados);
+    const falhouHttp = status >= 400;
+    for (const { nome: name, id } of mensagens) {
+        const { erro: isError, classe } = resolveDesfecho(id, desfechos, falhouHttp);
         try {
             analytics.writeDataPoint({
                 indexes: [name],
@@ -210,7 +204,7 @@ export function recordProtocolMethods(analytics, tag, body, status) {
                     tag?.self ? "self" : "",
                     tag?.country ?? "",
                     tag?.asOrg ?? "",
-                    "",
+                    classe,
                     "",
                     tag?.sessao ?? "",
                     name === "initialize" ? cliente : "",
@@ -222,7 +216,7 @@ export function recordProtocolMethods(analytics, tag, body, status) {
             // Falha de telemetria nunca quebra nem atrasa a resposta.
         }
     }
-    return nomes;
+    return mensagens.map((m) => m.nome);
 }
 /**
  * SESSÃO E CLIENTE (blobs 9 e 10, desde 2026-09-17).

package/dist/scraper/ecidadania.js

@@ -9,8 +9,10 @@
  * Everything here is pure parsing + fetch, with no MCP/tool/cache dependency, so it can be
  * driven by the Cron pipeline (step 3) and covered by fixture-based contract tests.
  */
+import { UpstreamError as PkgUpstreamError } from "@sbissoli/mcp-upstream";
 import { UPSTREAM_TIMEOUT_MS } from "../types.js";
 import { USER_AGENT } from "../version.js";
+import { upstreamCall } from "../throttle/upstream.js";
 export const ECIDADANIA_BASE = "https://www12.senado.leg.br/ecidadania";
 /**
  * Error carrying a `retryable` flag, mirroring UpstreamError so the tool layer
@@ -28,78 +30,69 @@ const isTransientStatus = (status) => status >= 500 || status === 429;
  * (`X-Requested-With: XMLHttpRequest`, wider `Accept`).
  */
 export async function fetchPage(path, opts = {}) {
-    const url = `${ECIDADANIA_BASE}${path}`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), UPSTREAM_TIMEOUT_MS);
-    try {
-        const resp = await fetch(url, {
-            headers: opts.ajax
-                ? { Accept: "text/html,*/*", "User-Agent": USER_AGENT, "X-Requested-With": "XMLHttpRequest" }
-                : { Accept: "text/html", "User-Agent": USER_AGENT },
-            signal: controller.signal,
-        });
-        clearTimeout(timeout);
-        if (!resp.ok) {
-            throw ecidadaniaFetchError(`e-Cidadania retornou HTTP ${resp.status} para ${path}`, isTransientStatus(resp.status));
-        }
-        const text = await resp.text();
-        // AJAX comment fragments are legitimately empty for events with zero comments — allowEmpty
-        // lets the caller treat "" as a valid (empty) result instead of a transient failure.
-        if (!opts.allowEmpty && !text.trim()) {
-            throw ecidadaniaFetchError(`e-Cidadania retornou página vazia para ${path}`, true);
-        }
-        return text;
-    }
-    catch (e) {
-        clearTimeout(timeout);
-        if (e.name === "AbortError") {
-            throw ecidadaniaFetchError(`e-Cidadania: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true);
-        }
-        if (e instanceof Error && "retryable" in e)
-            throw e; // already classified above
-        throw ecidadaniaFetchError(`e-Cidadania: falha de rede ao acessar ${path} (${e.message})`, true);
+    const resp = await idaEcidadania(path, opts.ajax
+        ? { Accept: "text/html,*/*", "User-Agent": USER_AGENT, "X-Requested-With": "XMLHttpRequest" }
+        : { Accept: "text/html", "User-Agent": USER_AGENT }, "e-Cidadania");
+    const text = await resp.text();
+    // AJAX comment fragments are legitimately empty for events with zero comments — allowEmpty
+    // lets the caller treat "" as a valid (empty) result instead of a transient failure.
+    if (!opts.allowEmpty && !text.trim()) {
+        throw ecidadaniaFetchError(`e-Cidadania retornou página vazia para ${path}`, true);
     }
+    return text;
 }
 /**
  * Fetch JSON from an e-Cidadania REST endpoint with validation.
  * Ensures the response is valid JSON and an array.
  */
 export async function fetchEcidadaniaJson(endpoint) {
-    const url = `${ECIDADANIA_BASE}${endpoint}`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), UPSTREAM_TIMEOUT_MS);
+    const resp = await idaEcidadania(endpoint, { Accept: "application/json", "User-Agent": USER_AGENT }, "e-Cidadania REST API");
+    let data;
     try {
-        const resp = await fetch(url, {
-            headers: { Accept: "application/json", "User-Agent": USER_AGENT },
-            signal: controller.signal,
-        });
-        clearTimeout(timeout);
-        if (!resp.ok) {
-            throw ecidadaniaFetchError(`e-Cidadania REST API retornou HTTP ${resp.status} para ${endpoint}`, isTransientStatus(resp.status));
-        }
-        let data;
-        try {
-            data = await resp.json();
-        }
-        catch {
-            throw ecidadaniaFetchError(`e-Cidadania REST API retornou JSON inválido para ${endpoint}`, true);
-        }
-        if (!Array.isArray(data)) {
-            // API returned an object or other non-array — wrap or return empty
-            if (data && typeof data === "object")
-                return [data];
-            return [];
-        }
-        return data;
+        data = await resp.json();
+    }
+    catch {
+        throw ecidadaniaFetchError(`e-Cidadania REST API retornou JSON inválido para ${endpoint}`, true);
+    }
+    if (!Array.isArray(data)) {
+        // API returned an object or other non-array — wrap or return empty
+        if (data && typeof data === "object")
+            return [data];
+        return [];
+    }
+    return data;
+}
+/**
+ * A ida ao portal, pelo fetch comum do portfólio (desde a 3.11.0; antes um
+ * `fetch` cru com timeout de 10 s e sem retry). Mesma política da API do Senado
+ * (`upstreamSenado`: teto 10 s, 5xx/429/rede repetem, timeout não) e mesmo
+ * coletor da chamada de tool — o detalhe raspado ao vivo entra no `retrieval`
+ * do bloco e-Cidadania. No cron (`scheduled`, fora de uma chamada) o coletor é
+ * descartável e a política vale igual. O token bucket NÃO se aplica: é outro
+ * host, e o portal nunca passou por ele. As mensagens e o `retryable` são os
+ * de antes — `ecidadaniaError` (tools) e o pipeline os leem.
+ */
+async function idaEcidadania(path, headers, rotulo) {
+    const url = `${ECIDADANIA_BASE}${path}`;
+    try {
+        return await upstreamCall().response(url, { headers });
     }
     catch (e) {
-        clearTimeout(timeout);
-        if (e.name === "AbortError") {
-            throw ecidadaniaFetchError(`e-Cidadania REST API: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${endpoint}`, true);
+        if (!(e instanceof PkgUpstreamError))
+            throw e;
+        switch (e.kind) {
+            case "timeout":
+            case "aborted":
+                throw ecidadaniaFetchError(`${rotulo}: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true);
+            case "network": {
+                const causa = e.cause instanceof Error ? e.cause.message : String(e.cause ?? "desconhecido");
+                throw ecidadaniaFetchError(`${rotulo}: falha de rede ao acessar ${path} (${causa})`, true);
+            }
+            default: {
+                const status = e.status ?? 502;
+                throw ecidadaniaFetchError(`${rotulo} retornou HTTP ${status} para ${path}`, isTransientStatus(status));
+            }
         }
-        if (e instanceof Error && "retryable" in e)
-            throw e; // already classified above
-        throw ecidadaniaFetchError(`e-Cidadania REST API: falha de rede ao acessar ${endpoint} (${e.message})`, true);
     }
 }
 /** Parse Brazilian number: 1.234.567 -> 1234567 */

package/dist/server.js

@@ -112,7 +112,7 @@ export function createServer(env, ctx, options = {}) {
                 openWorldHint: true,
             },
             _meta: toolMetaForProfile(toolProfile),
-        }, instrumentTool(name, profiledCallback, analytics, options.requestTag));
+        }, instrumentTool(name, profiledCallback, analytics, options.requestTag, options.gravados));
     };
     const baseUrl = env.SENADO_BASE_URL || "https://legis.senado.leg.br/dadosabertos";
     const admBaseUrl = env.SENADO_ADM_BASE_URL || "https://adm.senado.gov.br/adm-dadosabertos";