senado-br-mcp 3.10.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/instrument.js

@@ -32,6 +32,7 @@ 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";
 /**
@@ -71,7 +72,12 @@ export function instrumentTool(name, cb, analytics, tag, gravados) {
         // 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)

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/throttle/upstream.js

@@ -1,12 +1,62 @@
 /**
- * Upstream fetch wrapper with:
- * - Global rate limiting (token bucket)
- * - Concurrency limiting (max in-flight)
- * - Retry with bounded exponential backoff + jitter on 429/503, honoring the
- *   upstream Retry-After header when present (gives up early if it exceeds the budget)
- * - AbortController timeout (10s total)
- * - Response size guard (5 MB)
+ * Upstream fetch wrapper — a ida à API do Senado com:
+ * - Global rate limiting (token bucket) e concurrency limiting (max in-flight),
+ *   ANTES da ida, fora do pacote (política deste servidor);
+ * - Retry com backoff exponencial limitado + jitter em 429/503/5xx/rede, honrando
+ *   `Retry-After` e desistindo cedo se a espera estoura o orçamento;
+ * - Orçamento TOTAL de 10 s por ida (`UPSTREAM_TIMEOUT_MS`), esperas incluídas;
+ * - Guarda de tamanho da resposta (5 MB; 20 MB para os datasets grandes da ADM);
+ * - Contagem de idas, tentativas e anomalias para o bloco `retrieval` da
+ *   proveniência (contrato v1.1).
+ *
+ * Desde a 3.11.0 (2026-09-27) a ida em si — timeout, retry, orçamento, contagem —
+ * é feita pelo fetch comum do portfólio, `@sbissoli/mcp-upstream`, no modo
+ * `response` (o corpo continua sendo lido AQUI: as guardas de tamanho, o
+ * `rotaInexistente(corpo)` dos dois 404, o corpo vazio e o JSON inválido são
+ * semântica deste servidor, medida contra a fonte). O pacote CLASSIFICA; este
+ * módulo DECIDE. A classe `UpstreamError` local, as mensagens e o `transport`
+ * continuam os mesmos: `errorFrom`, `ehReuniaoInexistente`, `classifyError` e o
+ * disjuntor do contrato noturno (`scripts/contract/outage.ts`) leem todos eles.
+ *
+ * POLÍTICA (`UPSTREAM_POLICY`) — medida em 27/09/2026 com `curl` e o User-Agent
+ * do portfólio: a API legislativa responde em 0,3–1 s (`/senador/lista/atual`
+ * 0,7 s com 129 KB; `/plenario/lista/votacao` de um mês 0,9 s; a busca de matérias
+ * por palavra-chave teve UMA cauda fria de 7,4 s e depois 0,4–1 s); a API
+ * administrativa entrega 2,7 MB de contratos em 1,5 s e 9 MB de CEAPS em 1,9 s;
+ * o texto integral de um discurso sai em 0,35 s. Nenhuma origem chegou perto
+ * dos 10 s — o teto existe para a conexão pendurada, não para apressar a fonte.
+ *  - teto de UMA tentativa = orçamento TOTAL da ida = 10 s (paridade com o
+ *    desenho que este servidor já tinha: cada tentativa recebe o que sobra do
+ *    orçamento, e uma primeira tentativa pendurada gasta tudo);
+ *  - 2 retries (3 tentativas), backoff 1 s → 2 s → 4 s (teto) + jitter 0–500 ms.
+ *
+ * O QUE REPETE E O QUE NÃO (`retryUpstream`):
+ *  - 429 e 503 repetem, honrando `Retry-After`, como antes;
+ *  - **500/502 genéricos passam a repetir** (novo na 3.11.0): a classe já era
+ *    marcada `retryable: true` para o agente e este servidor não a repetia por
+ *    conta própria — o agente pagava a repetição. Paridade com os irmãos
+ *    (bcb/ibge/ilo/uis/medical repetem 5xx);
+ *  - **rede** (DNS/TCP/TLS) repete, como antes;
+ *  - **timeout NÃO repete**: a tentativa que pendurou já gastou o orçamento
+ *    inteiro (como antes: `AbortError` encerrava a ida);
+ *  - 4xx (404 incluído) não repete: é resposta da fonte, não falha;
+ *  - **corpo vazio e JSON inválido NÃO repetem** (como antes): são lidos aqui,
+ *    depois da ida, e há pelo menos um caso em que o corpo vazio é
+ *    determinístico (`/comissao/reuniao/{codigo}` inexistente — ver
+ *    `ehReuniaoInexistente`), em que repetir só atrasaria a resposta certa.
+ *
+ * O COLETOR. `instrumentTool` (src/instrument.ts) abre UM coletor por chamada de
+ * tool — aninhado ao ALS de cache que já existia — e toda ida feita aqui, a
+ * qualquer profundidade, cai nele; `provenanceFor` lê `currentRetrieval()`. Fora
+ * de uma chamada (cron do e-Cidadania, testes que chamam a função direto) a ida
+ * ganha um coletor descartável: a política vale igual, e o bloco diz
+ * `retrieval: null` ("não medido"), nunca quebra. Um servidor com UMA origem
+ * (a API do Senado, nas duas bases) não precisa do coletor por origem do
+ * medical — o `search` do Deep Research emite dois blocos da MESMA origem, e os
+ * dois carregam a medição da chamada.
  */
+import { createUpstream, UpstreamError as PkgUpstreamError, } from "@sbissoli/mcp-upstream";
+import { currentCall, withCall } from "@sbissoli/mcp-upstream/als";
 import { globalBucket } from "./token-bucket.js";
 import { UPSTREAM_TIMEOUT_MS, MAX_RESPONSE_SIZE, SENADO_BASE_URL_DEFAULT } from "../types.js";
 import { log, logger } from "../utils/logger.js";
@@ -85,30 +135,80 @@ export function rotaInexistente(corpo) {
     }
     return typeof detail === "string" && /^No static resource\b/i.test(detail.trim());
 }
+// ── Política de rede ──────────────────────────────────────────────────────────
+/** A política de rede deste servidor (ver o cabeçalho: números medidos em 27/09/2026). */
+export const UPSTREAM_POLICY = {
+    /** Teto de UMA tentativa (cabeçalhos + corpo), em ms. */
+    timeoutMs: UPSTREAM_TIMEOUT_MS,
+    /** Orçamento TOTAL de uma ida, esperas incluídas — o mesmo teto (paridade). */
+    budgetMs: UPSTREAM_TIMEOUT_MS,
+    /** Retries além da primeira tentativa. */
+    retries: MAX_RETRIES,
+    /** Esperas: 1 s, 2 s, 4 s (teto), mais jitter uniforme de até 500 ms. */
+    backoff: { baseMs: 1_000, maxMs: 4_000, jitterMs: 500 },
+};
+/**
+ * I/O da espera entre tentativas e do jitter, num objeto para os testes trocarem
+ * (`vi.spyOn(upstreamIo, "sleep")`): um 503 permanente num dublê custaria 3 s de
+ * backoff real por ida, e o jitter aleatório impediria contar o relógio.
+ */
+export const upstreamIo = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    random: () => Math.random(),
+};
+/** A decisão de repetir uma tentativa que falhou (o pacote diz a classe). */
+export function retryUpstream(ctx) {
+    switch (ctx.kind) {
+        case "rate_limited":
+        case "http_5xx":
+        case "network": {
+            logger.warn("upstream_retry", { url: ctx.url, attempt: ctx.attempt, kind: ctx.kind, status: ctx.status });
+            return true;
+        }
+        // A tentativa que pendurou já gastou o orçamento inteiro; 4xx é resposta da
+        // fonte; `malformed_body` não acontece no modo `response`.
+        default:
+            return false;
+    }
+}
 /**
- * Parse an HTTP Retry-After header (RFC 9110 §10.2.3) into milliseconds to wait.
- * Accepts the delta-seconds form ("5") and the HTTP-date form; returns null when
- * absent or unparseable, so the caller falls back to its own backoff.
+ * A política no formato do pacote, com ligação TARDIA ao `fetch` global — os
+ * testes dublam `globalThis.fetch` depois de este módulo carregar.
  */
-export function parseRetryAfterMs(value, now = Date.now()) {
-    if (!value)
-        return null;
-    const trimmed = value.trim();
-    if (/^\d+$/.test(trimmed)) {
-        return parseInt(trimmed, 10) * 1000;
-    }
-    const date = Date.parse(trimmed);
-    if (Number.isNaN(date))
-        return null;
-    return Math.max(0, date - now);
+export const upstreamSenado = createUpstream({
+    userAgent: USER_AGENT,
+    timeoutMs: UPSTREAM_POLICY.timeoutMs,
+    retries: UPSTREAM_POLICY.retries,
+    budgetMs: UPSTREAM_POLICY.budgetMs,
+    backoff: UPSTREAM_POLICY.backoff,
+    honorRetryAfter: true,
+    retryOn: retryUpstream,
+    sleep: (ms) => upstreamIo.sleep(ms),
+    random: () => upstreamIo.random(),
+    fetchImpl: (input, init) => globalThis.fetch(input, init),
+});
+/**
+ * Abre o coletor de UMA chamada de tool e roda `fn` dentro dele — ou reusa o que
+ * já está aberto, se `fn` é um passo de uma chamada maior (a tool de fora não
+ * pode perder as idas de dentro). É chamado por `instrumentTool`.
+ */
+export function withUpstreamCall(fn) {
+    return currentCall() ? fn() : withCall(upstreamSenado, () => fn());
 }
 /**
- * Wait before the next retry attempt: never less than the server's Retry-After
- * (when sent), never less than the client's own bounded exponential backoff.
+ * O coletor da chamada corrente; fora de uma chamada, um descartável (a ida
+ * continua com a política, a contagem simplesmente não é lida).
  */
-export function computeRetryWaitMs(attempt, retryAfterMs, jitterMs) {
-    const backoff = Math.min(1000 * Math.pow(2, attempt), 4000);
-    return Math.max(retryAfterMs ?? 0, backoff) + jitterMs;
+export function upstreamCall() {
+    return currentCall() ?? upstreamSenado.call();
+}
+/**
+ * O `retrieval` medido nesta chamada de tool — `null` fora de um coletor ou
+ * quando a resposta veio inteira do cache (nenhuma ida). É o que
+ * `provenanceFor` põe no bloco quando a tool não passa outro.
+ */
+export function currentRetrieval() {
+    return currentCall()?.retrieval() ?? null;
 }
 /**
  * Fetch from the Senado API upstream.
@@ -128,124 +228,119 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
             url.searchParams.set(key, params[key]);
         }
     }
+    // Check global rate limit — uma vez por IDA (as repetições de uma ida já
+    // estão limitadas em número e em orçamento; o balde protege a fonte da rajada
+    // de chamadas, não de uma tentativa a mais).
+    if (!globalBucket.tryConsume()) {
+        incr("upstreamErrors");
+        logger.warn("upstream_rate_limited", { path });
+        throw new UpstreamError(`[${path}] Taxa de requisições excedida. Tente novamente em alguns segundos.`, 429, true);
+    }
+    // Check concurrency limit
+    if (inFlight >= MAX_CONCURRENT) {
+        incr("upstreamErrors");
+        logger.warn("upstream_concurrency_limited", { path });
+        throw new UpstreamError(`[${path}] Muitas requisições simultâneas ao upstream. Tente novamente em breve.`, 503, true);
+    }
     const startTime = Date.now();
-    let lastError;
-    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-        // Check global rate limit
-        if (!globalBucket.tryConsume()) {
-            incr("upstreamErrors");
-            logger.warn("upstream_rate_limited", { path });
-            throw new UpstreamError(`[${path}] Taxa de requisições excedida. Tente novamente em alguns segundos.`, 429, true);
-        }
-        // Check concurrency limit
-        if (inFlight >= MAX_CONCURRENT) {
-            incr("upstreamErrors");
-            logger.warn("upstream_concurrency_limited", { path });
-            throw new UpstreamError(`[${path}] Muitas requisições simultâneas ao upstream. Tente novamente em breve.`, 503, true);
-        }
-        // Check remaining time budget
-        const elapsed = Date.now() - startTime;
-        const remaining = UPSTREAM_TIMEOUT_MS - elapsed;
-        if (remaining <= 0) {
-            lastError = lastError || new UpstreamError(`[${path}] Timeout: orçamento de ${UPSTREAM_TIMEOUT_MS}ms esgotado antes da tentativa ${attempt + 1}`, 504, true, true);
-            break;
-        }
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), remaining);
-        inFlight++;
-        try {
-            const response = await fetch(url.toString(), {
-                method: "GET",
-                headers: {
-                    Accept: "application/json",
-                    "User-Agent": USER_AGENT,
-                },
-                signal: controller.signal,
-            });
-            clearTimeout(timeout);
-            if (response.status === 429 || response.status === 503) {
-                lastError = new UpstreamError(`[${path}] Upstream retornou ${response.status}`, response.status, true);
-                if (attempt < MAX_RETRIES) {
-                    const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
-                    const wait = computeRetryWaitMs(attempt, retryAfterMs, Math.random() * 500);
-                    // Honoring a Retry-After longer than the remaining budget would just delay
-                    // the inevitable timeout — give up now and surface the retryable error.
-                    if (wait >= UPSTREAM_TIMEOUT_MS - (Date.now() - startTime)) {
-                        logger.warn("upstream_retry_abandoned", { path, attempt, status: response.status, retryAfterMs });
-                        break;
-                    }
-                    incr("upstreamRetries");
-                    logger.warn("upstream_retry", { path, attempt, status: response.status, retryAfterMs });
-                    await sleep(wait);
-                    continue;
-                }
-                break;
-            }
-            if (response.status === 404 && options.on404) {
-                incr("upstreamCalls");
-                log("upstream", path, 404, Date.now() - startTime, attempt);
-                const corpo404 = await response.text();
-                if (rotaInexistente(corpo404)) {
-                    throw new UpstreamError(`[${path}] ${MSG_ROTA_INEXISTENTE} — o caminho montado não existe na API do Senado.`, 404, false);
-                }
-                if (options.on404 === "empty")
-                    return [];
-                throw new RecursoAusenteError(path);
-            }
-            if (!response.ok) {
-                throw new UpstreamError(`[${path}] Upstream retornou HTTP ${response.status}`, response.status, response.status >= 500);
-            }
-            // Check response size via Content-Length header
-            const contentLength = response.headers.get("content-length");
-            if (contentLength && parseInt(contentLength, 10) > maxSize) {
-                throw new UpstreamError(`[${path}] Resposta upstream excede o limite de ${Math.round(maxSize / 1024 / 1024)} MB`, 413, false);
-            }
-            const text = await response.text();
-            if (text.length > maxSize) {
-                throw new UpstreamError(`[${path}] Resposta upstream excede o limite de ${Math.round(maxSize / 1024 / 1024)} MB`, 413, false);
-            }
-            const latency = Date.now() - startTime;
+    const call = upstreamCall();
+    const attemptsBefore = call.attempts;
+    const retriesFeitos = (attempts) => {
+        for (let i = 1; i < attempts; i++)
+            incr("upstreamRetries");
+    };
+    let response;
+    inFlight++;
+    try {
+        response = await call.response(url.toString(), {
+            method: "GET",
+            headers: {
+                Accept: options.accept ?? "application/json",
+                "User-Agent": USER_AGENT,
+            },
+        });
+    }
+    catch (err) {
+        if (!(err instanceof PkgUpstreamError))
+            throw err;
+        retriesFeitos(err.attempts);
+        if (err.kind === "not_found" && options.on404 && err.response) {
             incr("upstreamCalls");
-            log("upstream", path, response.status, latency, attempt);
-            if (!text.trim()) {
-                throw new UpstreamError(`[${path}] Resposta upstream vazia`, 502, true);
-            }
-            try {
-                return JSON.parse(text);
-            }
-            catch {
-                throw new UpstreamError(`[${path}] Resposta upstream não é JSON válido`, 502, false);
-            }
-        }
-        catch (err) {
-            clearTimeout(timeout);
-            if (err instanceof UpstreamError)
-                throw err;
-            // Network-level errors (DNS, TCP, TLS, AbortError)
-            const isAbort = err.name === "AbortError";
-            lastError = new UpstreamError(isAbort
-                ? `[${path}] Timeout na requisição upstream (${UPSTREAM_TIMEOUT_MS / 1000}s)`
-                : `[${path}] Erro de rede: ${err.message || "desconhecido"}`, isAbort ? 504 : 502, true, // Network errors are always retryable
-            true);
-            if (isAbort)
-                break; // AbortError means time budget is spent
-            if (attempt < MAX_RETRIES) {
-                incr("upstreamRetries");
-                logger.warn("upstream_retry", { path, attempt, message: lastError.message });
-                const backoff = Math.min(1000 * Math.pow(2, attempt), 4000);
-                await sleep(backoff + Math.random() * 500);
-                continue;
+            log("upstream", path, 404, Date.now() - startTime, err.attempts - 1);
+            const corpo404 = await err.response.text();
+            if (rotaInexistente(corpo404)) {
+                throw new UpstreamError(`[${path}] ${MSG_ROTA_INEXISTENTE} — o caminho montado não existe na API do Senado.`, 404, false);
             }
+            if (options.on404 === "empty")
+                return [];
+            throw new RecursoAusenteError(path);
         }
-        finally {
-            inFlight--;
+        const traduzido = traduzirErro(err, path);
+        if (traduzido.retryable) {
+            // O que hoje termina a ida por esgotamento (429/503/5xx/rede/timeout) é o
+            // que sempre contou como erro de upstream; 4xx e 404 são resposta da fonte.
+            incr("upstreamErrors");
+            logger.error("upstream_error", { path, status: traduzido.status, message: traduzido.message });
         }
+        throw traduzido;
+    }
+    finally {
+        inFlight--;
+    }
+    retriesFeitos(call.attempts - attemptsBefore);
+    // Check response size via Content-Length header
+    const contentLength = response.headers.get("content-length");
+    if (contentLength && parseInt(contentLength, 10) > maxSize) {
+        throw new UpstreamError(`[${path}] Resposta upstream excede o limite de ${Math.round(maxSize / 1024 / 1024)} MB`, 413, false);
+    }
+    const text = await response.text();
+    if (text.length > maxSize) {
+        throw new UpstreamError(`[${path}] Resposta upstream excede o limite de ${Math.round(maxSize / 1024 / 1024)} MB`, 413, false);
+    }
+    const latency = Date.now() - startTime;
+    incr("upstreamCalls");
+    log("upstream", path, response.status, latency, call.attempts - attemptsBefore - 1);
+    if (!text.trim()) {
+        throw new UpstreamError(`[${path}] Resposta upstream vazia`, 502, true);
+    }
+    if (options.text)
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UpstreamError(`[${path}] Resposta upstream não é JSON válido`, 502, false);
     }
-    const finalError = lastError || new UpstreamError(`[${path}] Falha ao acessar upstream após retries`, 502, true);
-    incr("upstreamErrors");
-    logger.error("upstream_error", { path, status: finalError.status, message: finalError.message });
-    throw finalError;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Do erro do pacote (classe + contagem) para o `UpstreamError` LOCAL que o resto
+ * do servidor lê — com as MESMAS mensagens de antes da 3.11.0: `errorFrom` mostra
+ * a mensagem ao agente, `classifyError` casa "upstream"/"timeout"/"5xx" nela, e
+ * `transport` alimenta o disjuntor do contrato noturno.
+ */
+export function traduzirErro(err, path) {
+    switch (err.kind) {
+        case "timeout":
+        case "aborted":
+            return new UpstreamError(`[${path}] Timeout na requisição upstream (${UPSTREAM_TIMEOUT_MS / 1000}s)`, 504, true, true);
+        case "network": {
+            const cause = err.cause;
+            const detalhe = cause instanceof Error ? cause.message : typeof cause === "string" ? cause : "";
+            return new UpstreamError(`[${path}] Erro de rede: ${detalhe || "desconhecido"}`, 502, true, true);
+        }
+        case "rate_limited":
+            return new UpstreamError(`[${path}] Upstream retornou 429`, 429, true);
+        case "http_5xx": {
+            const status = err.status ?? 502;
+            return status === 503
+                ? new UpstreamError(`[${path}] Upstream retornou 503`, 503, true)
+                : new UpstreamError(`[${path}] Upstream retornou HTTP ${status}`, status, true);
+        }
+        case "http_4xx":
+        case "not_found":
+            return new UpstreamError(`[${path}] Upstream retornou HTTP ${err.status ?? 404}`, err.status ?? 404, false);
+        case "malformed_body":
+            // Não acontece no modo `response` (o corpo é lido por `upstreamFetch`).
+            return new UpstreamError(`[${path}] Resposta upstream não é JSON válido`, 502, false);
+    }
 }

package/dist/tools/comissoes.js

@@ -13,13 +13,12 @@
  */
 import { z } from "zod";
 import { cachedFetch, cachedFetchWithMeta } from "../cache/manager.js";
-import { upstreamFetch } from "../throttle/upstream.js";
+import { upstreamFetch, UpstreamError } from "../throttle/upstream.js";
 import { toolError, errorFrom, ensureArray, safeInt, toBool, normalizeText } from "../utils/validation.js";
 import { digArrayRoot } from "../utils/upstream-parse.js";
 import { escolherReuniao, ehReuniaoInexistente, mensagemCodigoInexistente } from "./resolver-reuniao.js";
 import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
-import { CACHE_SEMI_STATIC, CACHE_DYNAMIC, CACHE_ON_DEMAND, UPSTREAM_TIMEOUT_MS } from "../types.js";
-import { USER_AGENT } from "../version.js";
+import { CACHE_SEMI_STATIC, CACHE_DYNAMIC, CACHE_ON_DEMAND } from "../types.js";
 export function formatDateYMD(d) {
     return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, "0")}${String(d.getDate()).padStart(2, "0")}`;
 }
@@ -423,50 +422,32 @@ export function registerComissoesTools(server, baseUrl) {
             const sigla = params.siglaCpi.toUpperCase();
             const pagina = params.pagina ?? 0;
             const { value: requerimentos, fetchedAt } = await cachedFetchWithMeta("senado_requerimentos_cpi", { sigla, pagina }, CACHE_DYNAMIC, async () => {
-                const url = `${baseUrl}/comissao/cpi/${sigla}/requerimentos.json?pagina=${pagina}`;
-                const controller = new AbortController();
-                const timeout = setTimeout(() => controller.abort(), UPSTREAM_TIMEOUT_MS);
+                // Pelo `upstreamFetch` desde a 3.11.0: antes era um `fetch` cru, sem
+                // token bucket, sem retry e fora da contagem do `retrieval`. O corpo
+                // vazio que esta rota devolve para CPI sem requerimentos vira `[]`
+                // aqui, porque o `upstreamFetch` o trata como resposta vazia (502).
+                let data;
                 try {
-                    const resp = await fetch(url, {
-                        headers: { Accept: "application/json", "User-Agent": USER_AGENT },
-                        signal: controller.signal,
-                    });
-                    clearTimeout(timeout);
-                    if (!resp.ok) {
-                        const body = await resp.text();
-                        const detail = (() => { try {
-                            return JSON.parse(body)?.detail;
-                        }
-                        catch {
-                            return null;
-                        } })();
-                        throw new Error(detail || `Upstream retornou HTTP ${resp.status} para requerimentos da ${sigla}`);
-                    }
-                    const text = await resp.text();
-                    if (!text.trim())
-                        return [];
-                    const data = JSON.parse(text);
-                    if (Array.isArray(data))
-                        return data;
-                    for (const v of Object.values(data)) {
-                        if (Array.isArray(v))
-                            return v;
-                        if (v && typeof v === "object") {
-                            for (const v2 of Object.values(v)) {
-                                if (Array.isArray(v2))
-                                    return v2;
-                            }
-                        }
-                    }
-                    return [data];
+                    data = await upstreamFetch(`/comissao/cpi/${sigla}/requerimentos`, { pagina: String(pagina) }, baseUrl);
                 }
                 catch (e) {
-                    clearTimeout(timeout);
-                    if (e.name === "AbortError") {
-                        throw new Error(`Timeout ao obter requerimentos da ${sigla}`);
-                    }
+                    if (e instanceof UpstreamError && /vazia/.test(e.message))
+                        return [];
                     throw e;
                 }
+                if (Array.isArray(data))
+                    return data;
+                for (const v of Object.values(data)) {
+                    if (Array.isArray(v))
+                        return v;
+                    if (v && typeof v === "object") {
+                        for (const v2 of Object.values(v)) {
+                            if (Array.isArray(v2))
+                                return v2;
+                        }
+                    }
+                }
+                return [data];
             });
             const prov = provenanceFor("SENADO_LEGIS", baseUrl, `/comissao/cpi/${sigla}/requerimentos`, {
                 dataset_id: `cpi=${sigla}; pagina=${pagina}`, retrieved_at: fetchedAt,

package/dist/tools/deep-research.js

@@ -103,13 +103,22 @@ async function construirIndice(baseUrl) {
     const comissoes = ensureArray(com.value?.ListaColegiados?.Colegiados?.Colegiado).map(parseComissaoItem);
     return {
         index: createIndex([...entradasSenadores(senadores), ...entradasComissoes(comissoes)]),
-        provenance: [
-            provenanceFor("SENADO_LEGIS", baseUrl, PATH_SENADORES, { dataset_id: "lista/atual", retrieved_at: sen.fetchedAt }),
-            provenanceFor("SENADO_LEGIS", baseUrl, PATH_COLEGIADOS, { retrieved_at: com.fetchedAt }),
-        ],
+        extraidoEm: { senadores: sen.fetchedAt, colegiados: com.fetchedAt },
         criadoEm: Date.now(),
     };
 }
+/**
+ * Proveniência das duas listas do índice — dois blocos da MESMA origem, e por
+ * isso os dois com o `retrieval` medido nesta chamada (o coletor é por chamada;
+ * ver src/throttle/upstream.ts). Chamada que só achou o índice pronto não foi
+ * à fonte, e os blocos dizem `retrieval: null`.
+ */
+function provenanciaDoIndice(baseUrl, indice) {
+    return [
+        provenanceFor("SENADO_LEGIS", baseUrl, PATH_SENADORES, { dataset_id: "lista/atual", retrieved_at: indice.extraidoEm.senadores }),
+        provenanceFor("SENADO_LEGIS", baseUrl, PATH_COLEGIADOS, { retrieved_at: indice.extraidoEm.colegiados }),
+    ];
+}
 /**
  * O índice da base, construído no primeiro uso e mantido por `INDICE_TTL_MS`.
  * Chamadas concorrentes compartilham a construção; falha não fica em cache.
@@ -182,7 +191,7 @@ function handlers(baseUrl) {
     async function search(query) {
         const indice = await obterIndice(baseUrl);
         const results = indice.index.search(query, { limit: DEEP_RESEARCH_LIMIT }).map(({ id, title, url }) => ({ id, title, url }));
-        return { results, extras: provenanceExtras(indice.provenance) };
+        return { results, extras: provenanceExtras(provenanciaDoIndice(baseUrl, indice)) };
     }
     async function fetch(id) {
         if (id.startsWith(PREFIXO_SENADOR)) {

package/dist/tools/discursos.js

@@ -10,8 +10,7 @@ import { upstreamFetch } from "../throttle/upstream.js";
 import { errorFrom, ensureArray, safeInt } from "../utils/validation.js";
 import { digArrayRoot } from "../utils/upstream-parse.js";
 import { provenanceFor, resultWithProvenance } from "../utils/provenance.js";
-import { CACHE_DYNAMIC, CACHE_ON_DEMAND, UPSTREAM_TIMEOUT_MS } from "../types.js";
-import { USER_AGENT } from "../version.js";
+import { CACHE_DYNAMIC, CACHE_ON_DEMAND } from "../types.js";
 /**
  * Aviso anexado quando `tipo=discursos` é chamado sem período. O upstream
  * `/senador/{cod}/discursos` limita a resposta aos últimos 30 dias quando
@@ -143,47 +142,21 @@ export function registerDiscursosTools(server, baseUrl) {
             const { value: texto, fetchedAt } = await cachedFetchWithMeta("senado_discurso_texto", { codigo: params.codigoPronunciamento }, CACHE_ON_DEMAND, async () => {
                 // This endpoint serves ONLY text/plain; the ".json" suffix (or Accept:
                 // application/json) forces content negotiation to JSON -> HTTP 406. No suffix
-                // + Accept including text/plain -> 200.
-                const url = `${baseUrl}/discurso/texto-integral/${params.codigoPronunciamento}`;
-                const controller = new AbortController();
-                const timeout = setTimeout(() => controller.abort(), UPSTREAM_TIMEOUT_MS);
+                // + Accept including text/plain -> 200. Pelo `upstreamFetch` em modo texto
+                // desde a 3.11.0 (antes: `fetch` cru, sem retry nem contagem no `retrieval`).
+                const text = (await upstreamFetch(`/discurso/texto-integral/${params.codigoPronunciamento}`, {}, baseUrl, { noJsonSuffix: true, text: true, accept: "text/plain, application/json" }));
+                // Try to parse as JSON first — API might wrap the text
                 try {
-                    const resp = await fetch(url, {
-                        method: "GET",
-                        headers: {
-                            Accept: "text/plain, application/json",
-                            "User-Agent": USER_AGENT,
-                        },
-                        signal: controller.signal,
-                    });
-                    clearTimeout(timeout);
-                    if (!resp.ok) {
-                        throw new Error(`Upstream retornou HTTP ${resp.status} para texto do discurso ${params.codigoPronunciamento}`);
-                    }
-                    const text = await resp.text();
-                    if (!text.trim()) {
-                        throw new Error(`Texto do discurso ${params.codigoPronunciamento} vazio`);
-                    }
-                    // Try to parse as JSON first — API might wrap the text
-                    try {
-                        const json = JSON.parse(text);
-                        // If it's an object with a text field, extract it
-                        if (json && typeof json === "object") {
-                            return json.TextoIntegral || json.textoIntegral || json.texto || text;
-                        }
-                        return text;
-                    }
-                    catch {
-                        // Not JSON — return raw text
-                        return text;
+                    const json = JSON.parse(text);
+                    // If it's an object with a text field, extract it
+                    if (json && typeof json === "object") {
+                        return json.TextoIntegral || json.textoIntegral || json.texto || text;
                     }
+                    return text;
                 }
-                catch (e) {
-                    clearTimeout(timeout);
-                    if (e.name === "AbortError") {
-                        throw new Error(`Timeout ao obter texto do discurso ${params.codigoPronunciamento}`);
-                    }
-                    throw e;
+                catch {
+                    // Not JSON — return raw text
+                    return text;
                 }
             });
             const prov = provenanceFor("SENADO_LEGIS", baseUrl, `/discurso/texto-integral/${params.codigoPronunciamento}`, { dataset_id: `codigoPronunciamento=${params.codigoPronunciamento}`, retrieved_at: fetchedAt });

package/dist/utils/provenance.js

@@ -39,6 +39,7 @@
  * mostram o IP do backend do provedor de IA, não o da pessoa).
  */
 import { createProvenanceContext, ptBR, toCanonicalIso, } from "@sbissoli/mcp-provenance";
+import { currentRetrieval } from "../throttle/upstream.js";
 /** Contexto único do servidor: namespace de `_meta`, idioma, fuso e modo default. */
 export const provenanceContext = createProvenanceContext({
     metaNamespace: "com.sidneybissoli.senado",
@@ -74,6 +75,7 @@ const extraToCanonical = (extra = {}) => ({
     ...(extra.field_sources !== undefined
         ? { field_sources: extra.field_sources.map(toCanonicalFieldSource) }
         : {}),
+    retrieval: extra.retrieval !== undefined ? extra.retrieval : currentRetrieval(),
 });
 /** Metadados estáticos por fonte upstream. source_url é montado por chamada (endpoint real). */
 export const SOURCES = {

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Single source of truth for the server version (kept in sync with package.json). */
-export const VERSION = "3.10.0";
+export const VERSION = "3.11.0";
 export const USER_AGENT = `senado-br-mcp/${VERSION} (+https://senado.sidneybissoli.com; sbissoli76@gmail.com)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "senado-br-mcp",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "license": "MIT",
   "type": "module",
@@ -50,9 +50,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
-    "@sbissoli/mcp-provenance": "^0.1.0",
+    "@sbissoli/mcp-provenance": "^0.2.0",
     "@sbissoli/mcp-search": "^0.5.0",
     "@sbissoli/mcp-stats": "^0.3.0",
+    "@sbissoli/mcp-upstream": "^0.3.0",
     "zod": "^4.5.4"
   },
   "devDependencies": {