senado-br-mcp 3.18.2 → 3.18.4

package/README.md

@@ -572,7 +572,7 @@ In addition to the `provenance` envelope, `structuredContent` carries a top-leve
 
 **Field-level granularity.** Most tools are single-source, so one envelope suffices. The few that merge reads in one response fill `field_sources` — a list of `{ fields, source_url, dataset_id, data_vintage, retrieved_at, served_from_cache }` attributing specific output fields to their real origin, and the block's `retrieved_at` is the oldest of them. `served_from_cache` is `true`/`false` for reads through the server cache and `null` where the notion does not apply (the bundled org-chart snapshot, the e-Cidadania corpus in D1). The merging tools (since 3.18.2): `senado_obter_materia` `secao=detalhe` (`/processo/{id}` + `ementa` from `/processo` + `relator` from `/processo/relatoria`), `senado_obter_senador` and the Deep Research `fetch` of a senator (biography + `mandatos`/`emExercicio` from `/senador/{codigo}/mandatos`), `senado_reunioes_comissao` over a window that crosses the year (one read per year), `senado_servidores` with `subordinadasA` (payroll + org-chart snapshot), `senado_suprimento_fundos` statistics on `atos-concessao` (acts + beneficiary names from the supridos registry), `senado_ecidadania_obter_evento` (live detail + `comentarios` from the corpus) and `senado_ecidadania_sugerir_tema_enquete` (consultas and ideias corpora). **Only a read that becomes a field of the answer is a sub-source**: a read that only resolves or checks an identifier (a committee acronym → its code, the parent check in `senado_contratacao_detalhe`) is left out, otherwise a cached lookup table would make the whole answer claim to be as old as it. `attribution` always lists every distinct underlying `source_url`.
 
-`retrieved_at` fidelity is provided by the cache layer (`cachedFetchWithMeta`), which persists the fetch timestamp alongside the value, so it reflects the real upstream extraction even on a cache hit. Two exceptions report an honest live timestamp instead: the e-Cidadania **list** tools (read from D1) use the corpus's `lastScrapedAt` — the true age of the stored data — while e-Cidadania **detail** tools, scraped live, use the fetch time and a level-3 canonical item URL. The only path that falls back to the build-time default is the in-code static reference catalog (`senado_tabelas_referencia` `tipos-materia`), which has no upstream extraction instant.
+`retrieved_at` fidelity is provided by the cache layer (`cachedFetchWithMeta`), which persists the fetch timestamp alongside the value, so it reflects the real upstream extraction even on a cache hit. Two exceptions report an honest live timestamp instead: the e-Cidadania **list** tools (read from D1) use the corpus's `lastScrapedAt` — the true age of the stored data, or the live scrape instant when the corpus is empty or stale and the list falls back to the portal (since 3.18.3; before, the stale corpus's instant leaked into the live answer) — while e-Cidadania **detail** tools, scraped live, use the fetch time and a level-3 canonical item URL. The only path that falls back to the build-time default is the in-code static reference catalog (`senado_tabelas_referencia` `tipos-materia`), which has no upstream extraction instant.
 
 Coverage is **universal**: all 69 tools carry the envelope — the 67 `senado_*` tools via `resultWithProvenance(` (verify with `grep -c 'resultWithProvenance(' src/tools/*.ts`) and the two Deep Research tools via `provenanceExtras` (same block, in `structuredContent`/`_meta`, since their text channel is the contract's JSON). The **⊕** marks in the inventory below denote the original pilot tools (votes, bills, processes); the envelope now extends to every tool, so the marks are historical.
 

package/dist/scraper/ecidadania.js

@@ -12,7 +12,7 @@
 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";
+import { CorpoForaDoPrazoError, PrazoDoCorpo, 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
@@ -36,10 +36,9 @@ const isTransientStatus = (status) => status >= 500 || status === 429;
  * (`X-Requested-With: XMLHttpRequest`, wider `Accept`).
  */
 export async function fetchPage(path, opts = {}) {
-    const resp = await idaEcidadania(path, opts.ajax
+    const text = 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()) {
@@ -52,10 +51,10 @@ export async function fetchPage(path, opts = {}) {
  * Ensures the response is valid JSON and an array.
  */
 export async function fetchEcidadaniaJson(endpoint) {
-    const resp = await idaEcidadania(endpoint, { Accept: "application/json", "User-Agent": USER_AGENT }, "e-Cidadania REST API");
+    const corpo = await idaEcidadania(endpoint, { Accept: "application/json", "User-Agent": USER_AGENT }, "e-Cidadania REST API");
     let data;
     try {
-        data = await resp.json();
+        data = JSON.parse(corpo);
     }
     catch {
         throw ecidadaniaFetchError(`e-Cidadania REST API retornou JSON inválido para ${endpoint}`, true);
@@ -77,11 +76,18 @@ export async function fetchEcidadaniaJson(endpoint) {
  * 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.
+ *
+ * Devolve o CORPO, lido aqui sob o que sobra dos 10 s (`PrazoDoCorpo`): no modo
+ * `response` o pacote só cobre até os cabeçalhos, e um portal que trava no
+ * corpo pendurava a chamada (e o cron) sem prazo.
  */
 async function idaEcidadania(path, headers, rotulo) {
     const url = `${ECIDADANIA_BASE}${path}`;
+    const prazo = new PrazoDoCorpo();
+    const foraDoPrazo = () => ecidadaniaFetchError(`${rotulo}: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true, "fonte");
+    let resp;
     try {
-        return await upstreamCall().response(url, { headers });
+        resp = await upstreamCall().response(url, { headers, signal: prazo.signal });
     }
     catch (e) {
         if (!(e instanceof PkgUpstreamError))
@@ -89,7 +95,7 @@ async function idaEcidadania(path, headers, rotulo) {
         switch (e.kind) {
             case "timeout":
             case "aborted":
-                throw ecidadaniaFetchError(`${rotulo}: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true, "fonte");
+                throw foraDoPrazo();
             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, "fonte");
@@ -108,6 +114,14 @@ async function idaEcidadania(path, headers, rotulo) {
             }
         }
     }
+    try {
+        return await prazo.texto(resp);
+    }
+    catch (e) {
+        if (e instanceof CorpoForaDoPrazoError)
+            throw foraDoPrazo();
+        throw e;
+    }
 }
 /** Parse Brazilian number: 1.234.567 -> 1234567 */
 export function parseBrNum(s) {

package/dist/scraper/store.js

@@ -99,7 +99,11 @@ export async function resolveList(db, entidade, staleMaxMin, liveScrape, now = n
             items: live,
             meta: {
                 fonte: "ao-vivo",
-                lastScrapedAt,
+                // The items were scraped NOW, so this is their age — not the stale D1's `lastScrapedAt`
+                // read above (until 3.18.2 it leaked here, and the tools' provenance said the live data
+                // was as old as the corpus, or carried no instant at all). An empty live list extracted
+                // nothing (consultas_votos' live path is a no-op `[]`), so it claims no instant.
+                lastScrapedAt: live.length > 0 ? new Date().toISOString() : null,
                 possivelDesatualizacao: false,
                 motivo: !db ? "d1-indisponivel" : d1Items.length === 0 ? "d1-vazio" : "d1-desatualizado",
             },

package/dist/throttle/upstream.js

@@ -213,6 +213,52 @@ export function withUpstreamCall(fn) {
 export function upstreamCall() {
     return currentCall() ?? upstreamSenado.call();
 }
+/** O corpo não chegou inteiro dentro do orçamento da ida (ver `PrazoDoCorpo`). */
+export class CorpoForaDoPrazoError extends Error {
+    constructor() {
+        super("corpo da resposta fora do prazo");
+        this.name = "CorpoForaDoPrazoError";
+    }
+}
+/**
+ * O prazo da LEITURA DO CORPO de uma ida no modo `response`.
+ *
+ * No modo `response` o `@sbissoli/mcp-upstream` (0.4.x) desarma o cronômetro da
+ * tentativa quando chegam os CABEÇALHOS: o corpo, lido aqui depois, ficava sem
+ * prazo nenhum, e uma fonte que manda os cabeçalhos e trava no corpo pendurava a
+ * chamada até o Worker morrer. Medido em 13/10/2026 ao subir o nock do medical
+ * (o `delay()` do nock 15 passou a segurar o corpo, não os cabeçalhos).
+ *
+ * O `signal` entra na ida e o pacote o combina ao dele; quem o aborta é SÓ
+ * `texto()`, depois dos cabeçalhos — durante a ida ele nunca dispara, então a
+ * classificação do pacote (timeout × abortado, a contagem do `retrieval`) não
+ * muda. O prazo do corpo é o que sobra do orçamento TOTAL da ida, contado do
+ * início dela: cabeçalhos + corpo cabem nos mesmos 10 s, como sempre se disse.
+ */
+export class PrazoDoCorpo {
+    #controller = new AbortController();
+    #inicio = Date.now();
+    /** Para passar na ida (`call.response(url, { signal })`). */
+    get signal() {
+        return this.#controller.signal;
+    }
+    /** Lê o corpo como texto; estourando o orçamento, lança `CorpoForaDoPrazoError`. */
+    async texto(response) {
+        const resta = UPSTREAM_POLICY.budgetMs - (Date.now() - this.#inicio);
+        const timer = setTimeout(() => this.#controller.abort(), Math.max(0, resta));
+        try {
+            return await response.text();
+        }
+        catch (e) {
+            if (this.#controller.signal.aborted)
+                throw new CorpoForaDoPrazoError();
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
 /**
  * O `retrieval` medido nesta chamada de tool — `null` fora de um coletor ou
  * quando a resposta veio inteira do cache (nenhuma ida). É o que
@@ -260,6 +306,20 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
         for (let i = 1; i < attempts; i++)
             incr("upstreamRetries");
     };
+    const prazo = new PrazoDoCorpo();
+    const lerCorpo = async (r) => {
+        try {
+            return await prazo.texto(r);
+        }
+        catch (e) {
+            if (e instanceof CorpoForaDoPrazoError) {
+                incr("upstreamErrors");
+                logger.error("upstream_error", { path, status: 504, message: "corpo fora do prazo" });
+                throw new UpstreamError(`[${path}] Timeout na requisição upstream (${UPSTREAM_TIMEOUT_MS / 1000}s)`, 504, true, true);
+            }
+            throw e;
+        }
+    };
     let response;
     inFlight++;
     try {
@@ -269,6 +329,7 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
                 Accept: options.accept ?? "application/json",
                 "User-Agent": USER_AGENT,
             },
+            signal: prazo.signal,
         });
     }
     catch (err) {
@@ -278,7 +339,7 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
         if (err.kind === "not_found" && options.on404 && err.response) {
             incr("upstreamCalls");
             log("upstream", path, 404, Date.now() - startTime, err.attempts - 1);
-            const corpo404 = await err.response.text();
+            const corpo404 = await lerCorpo(err.response);
             if (rotaInexistente(corpo404)) {
                 throw new UpstreamError(`[${path}] ${MSG_ROTA_INEXISTENTE} — o caminho montado não existe na API do Senado.`, 404, false, false, "defeito");
             }
@@ -305,7 +366,7 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
     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();
+    const text = await lerCorpo(response);
     if (text.length > maxSize) {
         throw new UpstreamError(`[${path}] Resposta upstream excede o limite de ${Math.round(maxSize / 1024 / 1024)} MB`, 413, false);
     }

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.18.2";
+export const VERSION = "3.18.4";
 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.18.2",
+  "version": "3.18.4",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "keywords": [
     "mcp",
@@ -83,7 +83,7 @@
     "@sbissoli/mcp-evals": "^0.2.1",
     "@sbissoli/mcp-surface": "^0.6.0",
     "@types/node": "^26.5.1",
-    "agents": "^0.26.0",
+    "agents": "^0.28.0",
     "exceljs": "^4.4.0",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2",