@cyanheads/congressgov-mcp-server 0.9.0 → 0.9.1

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.9.0
+**Version:** 0.9.1
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
@@ -74,7 +74,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 | `congressgov_member_lookup` | Discover members by state/district/congress, retrieve legislative portfolios |
 | `congressgov_committee_lookup` | Browse committees and retrieve legislation, reports, nominations |
 | `congressgov_roll_votes` | Retrieve House and Senate roll call votes and member voting positions |
-| `congressgov_senate_nominations` | Browse presidential nominations, track Senate confirmation pipeline |
+| `congressgov_senate_nominations` | Browse presidential nominations, track Senate confirmation pipeline; an action citing its own Senate record vote (`actions` rows, `latestAction` on `list`/`get`) carries `rollVote`, the `congressgov_roll_votes` arguments for it, from the 101st Congress on |
 | `congressgov_bill_summaries` | Browse recent CRS bill summaries — the "what's happening" feed, bounded by the shared summary page budget and per-row text window |
 | `congressgov_crs_reports` | Browse and retrieve nonpartisan CRS policy analysis reports |
 | `congressgov_committee_reports` | Browse and retrieve committee reports accompanying legislation + bounded report text via `content` |
@@ -111,11 +111,13 @@ src/
   config/
     server-config.ts                    # CONGRESS_API_KEY, base URL (Zod schema)
   services/
+    call-budget.ts                      # One 50 s upstream budget per tool call / resource read, shared by the three HTTP services
     congress-api/
       congress-api-service.ts           # API client — auth, pagination, rate limiting
       types.ts                          # API response types
     congress-documents/
-      congress-documents-service.ts     # www.congress.gov document fetch — host allowlist, byte ceiling, character window
+      congress-documents-service.ts     # www.congress.gov document fetch — host allowlist, byte ceiling, call budget, character window
+      document-body-cache.ts            # Process-local LRU of decompressed bodies — one fetch per document per TTL
       document-formats.ts               # Format label → URL resolution over upstream format lists
       extract-text.ts                   # GPO `<pre>` / XML body → deterministic plain text
       extract-text-stream.ts            # Incremental twin of extract-text.ts — one character window, constant memory
@@ -128,7 +130,7 @@ src/
       types.ts                          # Mirror row, search filters, search page types
     senate-lis/
       senate-vote-service.ts            # Senate LIS XML client — fetch, retry, not-found
-      parse.ts                          # pure XML → domain parsers (fast-xml-parser)
+      parse.ts                          # pure XML → domain parsers (fast-xml-parser); Senate vote coverage, session for a date
       types.ts                          # Senate vote domain types
   mcp-server/
     tools/definitions/
@@ -154,6 +156,7 @@ src/
       legislative-research.prompt.ts   # congressgov_legislative_research
   utils/
     character-references.ts             # Single-pass HTML/XML character-reference decoding
+    congress-calendar.ts                # ordinal(), congressFirstYear(), currentCongressNumber() — congress numbering arithmetic
 scripts/
   _mirror-context.ts                    # Shared bootstrap for the mirror lifecycle CLI scripts
   congress-mirror-init.ts               # mirror:init — full out-of-band mirror build
@@ -167,6 +170,12 @@ scripts/
 
 Four services. `CongressApiService` backs nine tools and the House branch of `congressgov_roll_votes`; `SenateVoteService` backs only the Senate branch of `congressgov_roll_votes` (the Congress.gov API exposes no Senate vote namespace); `CongressMirrorService` backs `congressgov_search_bills` only; `CongressDocumentsService` backs the `content` operation on `congressgov_bill_lookup`, `congressgov_committee_reports`, and `congressgov_daily_record`.
 
+**Call budget** (`call-budget.ts`, `withCallBudget`) — every upstream request a tool call or resource read makes through `CongressApiService`, `SenateVoteService`, or `CongressDocumentsService` spends one 50 s budget (`CALL_BUDGET_MS`) counted from the call's start (`ctx.timestamp`), so chained and parallel requests (a roster paged four times, a `content` lookup and then its document) end together before the 60 s default MCP client timeout:
+- Each request's retry ladder gets what is left as `withRetry` `deadlineMs`; each attempt's timeout (10 s API, 12 s Senate, 30 s document) is clamped to the remainder and its I/O carries the budget's signal
+- A backoff the remainder cannot hold fails at once as the expiry; a `Retry-After` wait it cannot hold fails at once with the upstream's own error and `retryAfter`; a request the spent budget cannot cover is never sent
+- Running out is `Timeout`, reason `upstream_timeout`, with `budgetMs` and `retryAttempts`. A caller abort stays `RequestCancelled`, and a 429 is still never retried
+- Services read the budget from the handler's own `ctx` — pass it to every service call, never a context derived from it (that carries a later timestamp). A request with no `ctx` — the mirror ingester and the `mirror:*` scripts — runs the plain per-request ladder, unbudgeted
+
 **`CongressApiService`** — wraps the Congress.gov REST API v3:
 - API key via `X-Api-Key` header (never logged; kept out of the URL so it can't leak in upstream error messages)
 - Pagination: `offset` + `limit` query params, max 250 per request
@@ -179,18 +188,22 @@ Four services. `CongressApiService` backs nine tools and the House branch of `co
 - The whole session menu is one file; each vote's roster ships inline — pagination is client-side
 - The host returns HTTP 200 with an HTML page for unknown congress/session/vote, so "not found" is detected from the body, not the status code
 - Party totals are derived from the roster (the feed publishes none)
+- senate.gov's firewall answers automated clients with HTTP 403, and a retry meets the same refusal: a 403 fails on the first attempt as `upstream_error` with `retryable: false` and a hint that House votes are unaffected, while a 5xx or timeout is retried within the call budget
 
 **`CongressDocumentsService`** — reads the document bodies behind Congress.gov's format URLs (`www.congress.gov`):
 - A second host, so a sibling service rather than a method on `CongressApiService` — no API key, no JSON, and enrolled omnibus bills that run to ten megabytes
 - URLs are resolved from upstream format metadata and checked against a `www.congress.gov` allowlist; a caller never supplies one
-- The fetch is bounded: a 25 MB ceiling (refused on `Content-Length`, else mid-stream), a 30s deadline, and a content-type allowlist
-- The body is extracted as it streams and only the requested window is retained, so a read's live set is flat in the size of the document (transient allocation is not — peak RSS runs above a buffered read); the ceiling bounds how long a response may run, not how much of one fits in a buffer
+- The fetch is bounded: a 25 MB ceiling (refused on `Content-Length`, else mid-stream), a content-type allowlist, and the call budget (above) — the api.congress.gov format lookup the handler makes first spends from it, and the document attempts and backoff share what is left
+- The body is extracted as it streams and only the requested window is extracted into memory; the ceiling bounds how long a response may run, not how much of one fits in a buffer (transient allocation still scales with the body — peak RSS runs above a buffered read)
+- A document that runs past its window keeps its decompressed body in `DocumentBodyCache` — process-local, one cache for every tenant (each body is public and fetched without credentials), 64 MB LRU, 16 MB per body (a larger one is captured until it passes that and then dropped), 10-minute TTL from insert — and later windows replay those bytes through the same extractor in 128 KiB slices with a macrotask between them: one fetch per document per TTL, and a replay never spends the budget. A window that reaches the end of its document caches nothing, a cancelled read caches nothing, and concurrent cold reads each fetch (no single-flight)
 - The structured response is bounded by an exact character window — `structuredContent.content.text` and its offsets index the extracted plain text and are never snapped to section breaks, so feeding `nextOffset` back walks a document with no overlap and no gap; `content[]` wraps that unchanged window in a dynamically safe Markdown fence for presentation
 - `extract-text.ts` unwraps GPO's `<pre>` print output verbatim (whitespace is the document's structure), while no-`<pre>` XML gains one space only at an otherwise-unseparated sibling close→open element boundary; both readings decode character references through `src/utils/character-references.ts` — the one decoder every HTML/XML → text path in the server shares, single-pass so an escaped reference stays escaped — and `extract-text-stream.ts` is their incremental twin, pinned byte-for-byte against the whole-string extractor
 
 **`CongressMirrorService`** — local SQLite FTS5 mirror of bill title + CRS summary text, backing `congressgov_search_bills` only:
 - Opt-in via `CONGRESS_MIRROR_ENABLED` (off by default); built out-of-band via the `mirror:init`/`mirror:refresh` scripts, never on server startup
 - No live-API fallback — ingests through the existing `CongressApiService`, and a mirror that hasn't finished its initial build returns an empty result with a notice, not an error
+- Every sync re-walks each congress's whole summaries list, requested from January 1 of the congress's first year with no end date (without `fromDateTime`, Congress.gov returns only the last day's summaries); the `updateDate` checkpoint is persisted only once the whole walk finishes; store spec `version: 2` migrates an older store by clearing its checkpoint, so the next sync backfills
+- The `mirror:*` scripts initialize the framework logger: log lines go to stderr as JSON, stdout carries only the script's own output
 - `createApp({ teardown })` stops the refresh schedule, cancels and awaits an active refresh, then closes the SQLite mirror. With `MCP_SESSION_MODE` unset, HTTP defaults to stateless; an explicit `MCP_SESSION_MODE` value still overrides it. No handler uses `ctx.requestInput`.
 
 **Usage in tools:**
@@ -199,7 +212,7 @@ import { getCongressApi } from '@/services/congress-api/congress-api-service.js'
 
 async handler(input, ctx) {
   const api = getCongressApi();
-  const bills = await api.listBills({ congress: input.congress, limit: input.limit });
+  const bills = await api.listBills({ congress: input.congress, limit: input.limit }, ctx);
   ctx.log.info('Bills fetched', { congress: input.congress, count: bills.bills.length });
   return bills;
 }
@@ -216,11 +229,13 @@ All tools share these patterns. The service layer handles them uniformly:
 | Condition | Error |
 |:----------|:------|
 | Rate limit hit | `rateLimited(...)` with `rate_limited`, credential/shared-quota guidance and upstream `Retry-After` when supplied |
-| Deadline or HTTP timeout | `Timeout` (-32004), `upstream_timeout`; HTTP responses retain status |
-| API unavailable (5xx) | `serviceUnavailable('Congress.gov API returned HTTP {status}.')` |
+| Attempt timeout, call budget spent, or HTTP timeout response | `Timeout` (-32004), `upstream_timeout`; a spent budget names it (`{upstream} did not deliver {request} within this call's 50-second budget for upstream requests (N attempts).`) and carries `budgetMs`/`retryAttempts`; HTTP responses retain status |
+| API unavailable (5xx) | `ServiceUnavailable` (-32000), `upstream_error`: `Congress.gov returned an unexpected error (HTTP {status}).`; a 501 carries `retryable: false` |
 | Entity not found (404) | `notFound('{entity} not found', { ...identifiers })` |
+| Upstream rejects the request (400, 401, 402, 403, 422) | `invalidParams('Congress.gov rejected the request as malformed (HTTP {status}).')`, `invalid_request` |
+| Rejected API key (401/403 whose body carries an api.data.gov `API_KEY_*` code) | `configurationError(...)` (-32008), `api_key_rejected`, `retryable: false`, gateway code in `data.upstreamCode` and the message; the hint tells the operator to replace or unset `CONGRESS_API_KEY` and never echoes the key. Classified on the body code, since a malformed path segment is also a plain 403 (#34) |
 | Invalid params | `validationError('...', { field })` |
-| Network error | `serviceUnavailable('Unable to reach the Congress.gov API.')` |
+| Network error | `ServiceUnavailable` (-32000), `upstream_error`: `Congress.gov returned an unexpected error.` |
 
 The `content` operation adds `documentErrorContracts` (tool-helpers) on top: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, and `offset_past_end` — the last of which `congressgov_bill_lookup` also raises from its `summaries` branch when `characterOffset` is past the end of every returned row's text. `CongressDocumentsService` raises each with a matching `data.reason`; the framework fills the declared `recovery` hint when the throw carries none, service throws included. Explicit recovery overrides win. A direct `definition.handler(...)` test sees the throw unchanged; retain `ctx.recoveryFor` where such a test asserts the hint, or assert the filled hint through `runToolContract`.
 

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.9.0
+**Version:** 0.9.1
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
@@ -74,7 +74,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 | `congressgov_member_lookup` | Discover members by state/district/congress, retrieve legislative portfolios |
 | `congressgov_committee_lookup` | Browse committees and retrieve legislation, reports, nominations |
 | `congressgov_roll_votes` | Retrieve House and Senate roll call votes and member voting positions |
-| `congressgov_senate_nominations` | Browse presidential nominations, track Senate confirmation pipeline |
+| `congressgov_senate_nominations` | Browse presidential nominations, track Senate confirmation pipeline; an action citing its own Senate record vote (`actions` rows, `latestAction` on `list`/`get`) carries `rollVote`, the `congressgov_roll_votes` arguments for it, from the 101st Congress on |
 | `congressgov_bill_summaries` | Browse recent CRS bill summaries — the "what's happening" feed, bounded by the shared summary page budget and per-row text window |
 | `congressgov_crs_reports` | Browse and retrieve nonpartisan CRS policy analysis reports |
 | `congressgov_committee_reports` | Browse and retrieve committee reports accompanying legislation + bounded report text via `content` |
@@ -111,11 +111,13 @@ src/
   config/
     server-config.ts                    # CONGRESS_API_KEY, base URL (Zod schema)
   services/
+    call-budget.ts                      # One 50 s upstream budget per tool call / resource read, shared by the three HTTP services
     congress-api/
       congress-api-service.ts           # API client — auth, pagination, rate limiting
       types.ts                          # API response types
     congress-documents/
-      congress-documents-service.ts     # www.congress.gov document fetch — host allowlist, byte ceiling, character window
+      congress-documents-service.ts     # www.congress.gov document fetch — host allowlist, byte ceiling, call budget, character window
+      document-body-cache.ts            # Process-local LRU of decompressed bodies — one fetch per document per TTL
       document-formats.ts               # Format label → URL resolution over upstream format lists
       extract-text.ts                   # GPO `<pre>` / XML body → deterministic plain text
       extract-text-stream.ts            # Incremental twin of extract-text.ts — one character window, constant memory
@@ -128,7 +130,7 @@ src/
       types.ts                          # Mirror row, search filters, search page types
     senate-lis/
       senate-vote-service.ts            # Senate LIS XML client — fetch, retry, not-found
-      parse.ts                          # pure XML → domain parsers (fast-xml-parser)
+      parse.ts                          # pure XML → domain parsers (fast-xml-parser); Senate vote coverage, session for a date
       types.ts                          # Senate vote domain types
   mcp-server/
     tools/definitions/
@@ -154,6 +156,7 @@ src/
       legislative-research.prompt.ts   # congressgov_legislative_research
   utils/
     character-references.ts             # Single-pass HTML/XML character-reference decoding
+    congress-calendar.ts                # ordinal(), congressFirstYear(), currentCongressNumber() — congress numbering arithmetic
 scripts/
   _mirror-context.ts                    # Shared bootstrap for the mirror lifecycle CLI scripts
   congress-mirror-init.ts               # mirror:init — full out-of-band mirror build
@@ -167,6 +170,12 @@ scripts/
 
 Four services. `CongressApiService` backs nine tools and the House branch of `congressgov_roll_votes`; `SenateVoteService` backs only the Senate branch of `congressgov_roll_votes` (the Congress.gov API exposes no Senate vote namespace); `CongressMirrorService` backs `congressgov_search_bills` only; `CongressDocumentsService` backs the `content` operation on `congressgov_bill_lookup`, `congressgov_committee_reports`, and `congressgov_daily_record`.
 
+**Call budget** (`call-budget.ts`, `withCallBudget`) — every upstream request a tool call or resource read makes through `CongressApiService`, `SenateVoteService`, or `CongressDocumentsService` spends one 50 s budget (`CALL_BUDGET_MS`) counted from the call's start (`ctx.timestamp`), so chained and parallel requests (a roster paged four times, a `content` lookup and then its document) end together before the 60 s default MCP client timeout:
+- Each request's retry ladder gets what is left as `withRetry` `deadlineMs`; each attempt's timeout (10 s API, 12 s Senate, 30 s document) is clamped to the remainder and its I/O carries the budget's signal
+- A backoff the remainder cannot hold fails at once as the expiry; a `Retry-After` wait it cannot hold fails at once with the upstream's own error and `retryAfter`; a request the spent budget cannot cover is never sent
+- Running out is `Timeout`, reason `upstream_timeout`, with `budgetMs` and `retryAttempts`. A caller abort stays `RequestCancelled`, and a 429 is still never retried
+- Services read the budget from the handler's own `ctx` — pass it to every service call, never a context derived from it (that carries a later timestamp). A request with no `ctx` — the mirror ingester and the `mirror:*` scripts — runs the plain per-request ladder, unbudgeted
+
 **`CongressApiService`** — wraps the Congress.gov REST API v3:
 - API key via `X-Api-Key` header (never logged; kept out of the URL so it can't leak in upstream error messages)
 - Pagination: `offset` + `limit` query params, max 250 per request
@@ -179,18 +188,22 @@ Four services. `CongressApiService` backs nine tools and the House branch of `co
 - The whole session menu is one file; each vote's roster ships inline — pagination is client-side
 - The host returns HTTP 200 with an HTML page for unknown congress/session/vote, so "not found" is detected from the body, not the status code
 - Party totals are derived from the roster (the feed publishes none)
+- senate.gov's firewall answers automated clients with HTTP 403, and a retry meets the same refusal: a 403 fails on the first attempt as `upstream_error` with `retryable: false` and a hint that House votes are unaffected, while a 5xx or timeout is retried within the call budget
 
 **`CongressDocumentsService`** — reads the document bodies behind Congress.gov's format URLs (`www.congress.gov`):
 - A second host, so a sibling service rather than a method on `CongressApiService` — no API key, no JSON, and enrolled omnibus bills that run to ten megabytes
 - URLs are resolved from upstream format metadata and checked against a `www.congress.gov` allowlist; a caller never supplies one
-- The fetch is bounded: a 25 MB ceiling (refused on `Content-Length`, else mid-stream), a 30s deadline, and a content-type allowlist
-- The body is extracted as it streams and only the requested window is retained, so a read's live set is flat in the size of the document (transient allocation is not — peak RSS runs above a buffered read); the ceiling bounds how long a response may run, not how much of one fits in a buffer
+- The fetch is bounded: a 25 MB ceiling (refused on `Content-Length`, else mid-stream), a content-type allowlist, and the call budget (above) — the api.congress.gov format lookup the handler makes first spends from it, and the document attempts and backoff share what is left
+- The body is extracted as it streams and only the requested window is extracted into memory; the ceiling bounds how long a response may run, not how much of one fits in a buffer (transient allocation still scales with the body — peak RSS runs above a buffered read)
+- A document that runs past its window keeps its decompressed body in `DocumentBodyCache` — process-local, one cache for every tenant (each body is public and fetched without credentials), 64 MB LRU, 16 MB per body (a larger one is captured until it passes that and then dropped), 10-minute TTL from insert — and later windows replay those bytes through the same extractor in 128 KiB slices with a macrotask between them: one fetch per document per TTL, and a replay never spends the budget. A window that reaches the end of its document caches nothing, a cancelled read caches nothing, and concurrent cold reads each fetch (no single-flight)
 - The structured response is bounded by an exact character window — `structuredContent.content.text` and its offsets index the extracted plain text and are never snapped to section breaks, so feeding `nextOffset` back walks a document with no overlap and no gap; `content[]` wraps that unchanged window in a dynamically safe Markdown fence for presentation
 - `extract-text.ts` unwraps GPO's `<pre>` print output verbatim (whitespace is the document's structure), while no-`<pre>` XML gains one space only at an otherwise-unseparated sibling close→open element boundary; both readings decode character references through `src/utils/character-references.ts` — the one decoder every HTML/XML → text path in the server shares, single-pass so an escaped reference stays escaped — and `extract-text-stream.ts` is their incremental twin, pinned byte-for-byte against the whole-string extractor
 
 **`CongressMirrorService`** — local SQLite FTS5 mirror of bill title + CRS summary text, backing `congressgov_search_bills` only:
 - Opt-in via `CONGRESS_MIRROR_ENABLED` (off by default); built out-of-band via the `mirror:init`/`mirror:refresh` scripts, never on server startup
 - No live-API fallback — ingests through the existing `CongressApiService`, and a mirror that hasn't finished its initial build returns an empty result with a notice, not an error
+- Every sync re-walks each congress's whole summaries list, requested from January 1 of the congress's first year with no end date (without `fromDateTime`, Congress.gov returns only the last day's summaries); the `updateDate` checkpoint is persisted only once the whole walk finishes; store spec `version: 2` migrates an older store by clearing its checkpoint, so the next sync backfills
+- The `mirror:*` scripts initialize the framework logger: log lines go to stderr as JSON, stdout carries only the script's own output
 - `createApp({ teardown })` stops the refresh schedule, cancels and awaits an active refresh, then closes the SQLite mirror. With `MCP_SESSION_MODE` unset, HTTP defaults to stateless; an explicit `MCP_SESSION_MODE` value still overrides it. No handler uses `ctx.requestInput`.
 
 **Usage in tools:**
@@ -199,7 +212,7 @@ import { getCongressApi } from '@/services/congress-api/congress-api-service.js'
 
 async handler(input, ctx) {
   const api = getCongressApi();
-  const bills = await api.listBills({ congress: input.congress, limit: input.limit });
+  const bills = await api.listBills({ congress: input.congress, limit: input.limit }, ctx);
   ctx.log.info('Bills fetched', { congress: input.congress, count: bills.bills.length });
   return bills;
 }
@@ -216,11 +229,13 @@ All tools share these patterns. The service layer handles them uniformly:
 | Condition | Error |
 |:----------|:------|
 | Rate limit hit | `rateLimited(...)` with `rate_limited`, credential/shared-quota guidance and upstream `Retry-After` when supplied |
-| Deadline or HTTP timeout | `Timeout` (-32004), `upstream_timeout`; HTTP responses retain status |
-| API unavailable (5xx) | `serviceUnavailable('Congress.gov API returned HTTP {status}.')` |
+| Attempt timeout, call budget spent, or HTTP timeout response | `Timeout` (-32004), `upstream_timeout`; a spent budget names it (`{upstream} did not deliver {request} within this call's 50-second budget for upstream requests (N attempts).`) and carries `budgetMs`/`retryAttempts`; HTTP responses retain status |
+| API unavailable (5xx) | `ServiceUnavailable` (-32000), `upstream_error`: `Congress.gov returned an unexpected error (HTTP {status}).`; a 501 carries `retryable: false` |
 | Entity not found (404) | `notFound('{entity} not found', { ...identifiers })` |
+| Upstream rejects the request (400, 401, 402, 403, 422) | `invalidParams('Congress.gov rejected the request as malformed (HTTP {status}).')`, `invalid_request` |
+| Rejected API key (401/403 whose body carries an api.data.gov `API_KEY_*` code) | `configurationError(...)` (-32008), `api_key_rejected`, `retryable: false`, gateway code in `data.upstreamCode` and the message; the hint tells the operator to replace or unset `CONGRESS_API_KEY` and never echoes the key. Classified on the body code, since a malformed path segment is also a plain 403 (#34) |
 | Invalid params | `validationError('...', { field })` |
-| Network error | `serviceUnavailable('Unable to reach the Congress.gov API.')` |
+| Network error | `ServiceUnavailable` (-32000), `upstream_error`: `Congress.gov returned an unexpected error.` |
 
 The `content` operation adds `documentErrorContracts` (tool-helpers) on top: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, and `offset_past_end` — the last of which `congressgov_bill_lookup` also raises from its `summaries` branch when `characterOffset` is past the end of every returned row's text. `CongressDocumentsService` raises each with a matching `data.reason`; the framework fills the declared `recovery` hint when the throw carries none, service throws included. Explicit recovery overrides win. A direct `definition.handler(...)` test sees the throw unchanged; retain `ctx.recoveryFor` where such a test asserts the hint, or assert the filled hint through `runToolContract`.
 

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.9.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/congressgov-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/congressgov-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/congressgov-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.9.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/congressgov-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/congressgov-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/congressgov-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -107,8 +107,10 @@ Bill, member, and committee data is also reachable through `congressgov_bill_loo
 ### `congressgov_roll_votes` <sub>tool</sub>
 
 - `chamber` is `house` (default, Congress.gov API) or `senate` (the Senate's LIS feed); every call needs `congress` + `session` (1 or 2), and `get`/`members` add `voteNumber`, which resets each session and is specific to one chamber
+- A congress's first year is session 1 and its second year session 2, but a second session can run into January 1–3 of the following year (the 116th Congress's second session voted on 2021-01-01)
 - `list` is newest first unless `order: 'oldest'`; `get` returns the question, result, tallies, and party breakdown, and `members` returns each member's position
 - Senate votes start at the 101st Congress (1989), and Senate rows pair the feed's year-less `voteDate` with a derived `voteDateIso`
+- When senate.gov refuses the request (HTTP 403, which its firewall returns to automated clients), a Senate call fails on the first attempt with a non-retryable `upstream_error`; a 5xx or timeout from the feed is retried. House votes are unaffected
 
 ---
 
@@ -116,6 +118,7 @@ Bill, member, and committee data is also reachable through `congressgov_bill_loo
 
 - `list` browses one `congress`; `get`, `actions`, `committees`, `hearings`, and `nominees` need a `nominationNumber` (`1000` for PN1000), and `nominees` also needs an `ordinal` from the `nominees` array `get` returns
 - Multi-part nominations (e.g. PN851) keep their activity on partitioned children (`851-1`, `851-2`, …); an empty sub-resource call on the bare number returns a notice pointing there
+- An action whose text cites its own Senate record vote (`Record Vote Number: 225.`) carries `rollVote` — `{ chamber: 'senate', congress, session, voteNumber }`, the `congressgov_roll_votes` arguments for that vote. Every citing `actions` row gets one, cloture votes included, and so does `latestAction` on `list` rows and `get`; votes before the 101st Congress get none
 
 ---
 
@@ -212,7 +215,8 @@ Congress.gov-specific:
 
 - Type-safe client for the Congress.gov REST API v3, plus a client for the Senate's LIS XML feed that backs Senate roll votes
 - The Congress.gov API has no keyword search, so tools browse by congress, type, date range, chamber, state, and district; list operations page with `limit` 1–250 (default 20) and `offset`
-- `content` on bill text, committee reports, and Record articles reads `format` `text` (default) or `xml` in a `characterOffset`/`characterLimit` window (1–100,000 characters, default 25,000), fetched only from `www.congress.gov` under a 25 MB ceiling and a 30s deadline
+- `content` on bill text, committee reports, and Record articles reads `format` `text` (default) or `xml` in a `characterOffset`/`characterLimit` window (1–100,000 characters, default 25,000), fetched only from `www.congress.gov` under a 25 MB ceiling; a document longer than one window (up to 16 MB) is downloaded once and its later windows are served from a 10-minute in-memory cache
+- Each tool call or resource read gets 50 seconds for all of its upstream requests, retries and backoff included, whether it makes one request or chains several (a `content` call's metadata lookup and document fetch, a committee name resolved against the full roster). A stalled upstream ends the call before the 60-second default timeout of MCP clients: `upstream_timeout` from Congress.gov, the retryable `upstream_error` from the Senate LIS feed
 - Optional API key from [api.data.gov](https://api.data.gov/signup/): `DEMO_KEY` allows 30 requests/hour and 50/day per IP, registered keys 5,000/hour
 - Opt-in local SQLite FTS5 mirror (`CONGRESS_MIRROR_ENABLED`) adds keyword search over bill titles and CRS summaries
 
@@ -221,7 +225,7 @@ Agent-friendly output:
 - Every list response carries `effectiveQuery` and `totalCount`, with a `notice` when nothing matched
 - `list` rejects detail-only identifiers (`billNumber`, `voteNumber`, `nominationNumber`, `reportNumber`, `volumeNumber`) with an `incompatible_identity` error that names the operation to use instead
 - `content` returns `offset`, `truncated`, and `nextOffset`, so walking a multi-megabyte bill never skips or repeats a character
-- Typed failures (`document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, `offset_past_end`, `not_found`, `rate_limited`, `invalid_request`, `upstream_error`, `upstream_timeout`), each with a recovery hint
+- Typed failures (`document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, `offset_past_end`, `not_found`, `rate_limited`, `invalid_request`, `api_key_rejected`, `upstream_error`, `upstream_timeout`), each with a recovery hint
 
 ## Getting started
 
@@ -332,11 +336,12 @@ The image defaults to HTTP transport, stateless session mode, and logs to `/var/
 | `src/mcp-server/tools/` | Tool definitions (`definitions/*.tool.ts`) plus shared input, formatting, and summary-window helpers. |
 | `src/mcp-server/resources/definitions/` | Resource definitions (`*.resource.ts`). |
 | `src/mcp-server/prompts/definitions/` | Prompt definitions (`*.prompt.ts`). |
+| `src/services/call-budget.ts` | The 50-second budget every tool call's upstream requests share. |
 | `src/services/congress-api/` | Congress.gov API client: auth, pagination, rate limiting. |
-| `src/services/congress-documents/` | Bounded document-text fetch: host allowlist, byte ceiling, character window. |
+| `src/services/congress-documents/` | Bounded document-text fetch: host allowlist, byte ceiling, character window, and a 10-minute cache of document bodies. |
 | `src/services/congress-mirror/` | Local SQLite FTS5 bill-search mirror: ingest, normalize, schema. |
 | `src/services/senate-lis/` | Senate LIS XML client for Senate roll call votes. |
-| `src/utils/` | HTML/XML character-reference decoding. |
+| `src/utils/` | HTML/XML character-reference decoding and congress-number arithmetic. |
 | `scripts/` | Build, devcheck, and release tooling, plus the `mirror:init` / `mirror:refresh` / `mirror:verify` CLIs. |
 | `tests/` | Unit and integration tests, mirroring the `src/` structure. |
 

package/changelog/0.9.x/0.9.1.md

@@ -0,0 +1,31 @@
+---
+summary: "Rejected API keys get a distinct error, each tool call shares a 50-second upstream budget, nomination actions point at their Senate roll votes, and the bill mirror stores summaries."
+breaking: false
+security: false
+---
+
+# 0.9.1 — 2026-11-01
+
+## Added
+
+- **`rollVote` on nomination actions** — `congressgov_senate_nominations` `actions` rows, and `latestAction` on `list` and `get`, carry `{ chamber: 'senate', congress, session, voteNumber }`, the `congressgov_roll_votes` arguments for the Senate record vote the action cites (101st Congress onward) (#62).
+
+## Changed
+
+- **Upstream call budget** — every tool call or resource read gets one 50-second budget across its upstream requests, retries, and backoff; running out is `Timeout` `upstream_timeout` with `budgetMs` and `retryAttempts`. The shared `upstream_error` and `upstream_timeout` contract descriptions match (#88).
+- **`content` document cache** — a multi-window document is fetched once per 10-minute TTL instead of once per window; bodies up to 16 MB are cached, 64 MB total, process-local (#57).
+- **`congressgov_roll_votes` `session`** — the description no longer states an odd/even-year rule; a second session can run into January 1–3 (#62).
+- **Mirror store spec** — moves to `version: 2`; its migration clears the checkpoint so the next sync backfills summaries (#86).
+
+## Fixed
+
+- **Rejected API key** — an api.data.gov `API_KEY_*` code on a 401 or 403 is now `-32008` `api_key_rejected` (not retryable, gateway code in `data.upstreamCode`) with a hint to replace or unset `CONGRESS_API_KEY`, instead of `invalid_request`; other 400/401/403/422 responses keep `invalid_request` (#84).
+- **Senate 403** — a senate.gov HTTP 403 fails on the first attempt as a non-retryable `upstream_error` that says House votes are unaffected; 5xx and timeouts are still retried (#89).
+- **Mirror summaries** — `mirror:init` and `mirror:refresh` request each congress's summaries from January 1 of its first year; without a date window Congress.gov returned only the last day's (#86).
+- **Mirror refresh checkpoint** — persisted only with the final page of a completed walk, so a refresh that fails partway no longer advances it past a later congress (#91).
+- **Mirror CLI output** — `mirror:init`, `mirror:refresh`, and `mirror:verify` log to stderr instead of printing nothing (#87).
+
+## Dependencies
+
+- `@biomejs/biome` ^2.6.3 → ^2.6.4.
+- `@types/node` ^26.6.5 → ^26.6.6.

package/dist/config/server-config.d.ts

@@ -5,13 +5,6 @@
 import { z } from '@cyanheads/mcp-ts-core';
 /** Default on-disk location of the SQLite bill FTS mirror. */
 export declare const DEFAULT_MIRROR_PATH = ".mirror/bills.sqlite3";
-/**
- * Congress number covering a given date. The 1st U.S. Congress convened in 1789
- * and each Congress spans two years, so `floor((year - 1789) / 2) + 1` yields the
- * ordinal (2025–2026 → 119). Used to seed the default mirror window when
- * `CONGRESS_MIRROR_CONGRESSES` is unset.
- */
-export declare function currentCongressNumber(date?: Date): number;
 declare const ServerConfigSchema: z.ZodObject<{
     apiKey: z.ZodDefault<z.ZodString>;
     baseUrl: z.ZodDefault<z.ZodString>;

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CAErE;AAoBD,QAAA,MAAM,kBAAkB;;;;;;;iBA6CtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAU9C;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAI3C,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAoB3D,QAAA,MAAM,kBAAkB;;;;;;;iBA6CtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAU9C;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/config/server-config.js

@@ -4,17 +4,9 @@
  */
 import { z } from '@cyanheads/mcp-ts-core';
 import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+import { currentCongressNumber } from '../utils/congress-calendar.js';
 /** Default on-disk location of the SQLite bill FTS mirror. */
 export const DEFAULT_MIRROR_PATH = '.mirror/bills.sqlite3';
-/**
- * Congress number covering a given date. The 1st U.S. Congress convened in 1789
- * and each Congress spans two years, so `floor((year - 1789) / 2) + 1` yields the
- * ordinal (2025–2026 → 119). Used to seed the default mirror window when
- * `CONGRESS_MIRROR_CONGRESSES` is unset.
- */
-export function currentCongressNumber(date = new Date()) {
-    return Math.floor((date.getUTCFullYear() - 1789) / 2) + 1;
-}
 /**
  * Parse `CONGRESS_MIRROR_CONGRESSES` — a comma-separated list of congress numbers
  * ("118,119") — into a positive-integer array. Unset/empty falls back to the

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAI,GAAS,IAAI,IAAI,EAAE;IAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,OAAO,KAAK;aACT,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;aACzC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;IACxC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CACP,4KAA4K,CAC7K;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,6BAA6B,CAAC;SACtC,QAAQ,CAAC,2BAA2B,CAAC;IAExC;;;;OAIG;IACH,aAAa,EAAE,CAAC;SACb,UAAU,EAAE;SACZ,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,4EAA4E,CAAC;IACzF,8FAA8F;IAC9F,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,OAAO,CAAC,mBAAmB,CAAC;SAC5B,QAAQ,CAAC,kDAAkD,CAAC;IAC/D;;;OAGG;IACH,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,oFAAoF,CAAC;IACjG;;;;OAIG;IACH,UAAU,EAAE,CAAC;SACV,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACxE,QAAQ,CAAC,uEAAuE,CAAC;CACrF,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,kBAAkB;QAC1B,OAAO,EAAE,uBAAuB;QAChC,aAAa,EAAE,yBAAyB;QACxC,UAAU,EAAE,sBAAsB;QAClC,iBAAiB,EAAE,8BAA8B;QACjD,UAAU,EAAE,4BAA4B;KACzC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,SAAS,CAAC;AACtB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,8DAA8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE3D;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,OAAO,KAAK;aACT,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;aACzC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;IACxC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CACP,4KAA4K,CAC7K;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,6BAA6B,CAAC;SACtC,QAAQ,CAAC,2BAA2B,CAAC;IAExC;;;;OAIG;IACH,aAAa,EAAE,CAAC;SACb,UAAU,EAAE;SACZ,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,4EAA4E,CAAC;IACzF,8FAA8F;IAC9F,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,OAAO,CAAC,mBAAmB,CAAC;SAC5B,QAAQ,CAAC,kDAAkD,CAAC;IAC/D;;;OAGG;IACH,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,oFAAoF,CAAC;IACjG;;;;OAIG;IACH,UAAU,EAAE,CAAC;SACV,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACxE,QAAQ,CAAC,uEAAuE,CAAC;CACrF,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,kBAAkB;QAC1B,OAAO,EAAE,uBAAuB;QAChC,aAAa,EAAE,yBAAyB;QACxC,UAAU,EAAE,sBAAsB;QAClC,iBAAiB,EAAE,8BAA8B;QACjD,UAAU,EAAE,4BAA4B;KACzC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,SAAS,CAAC;AACtB,CAAC"}

package/dist/mcp-server/tools/definitions/bill-lookup.tool.d.ts

@@ -75,19 +75,26 @@ export declare const billLookupTool: import("@cyanheads/mcp-ts-core").ToolDefini
     readonly retryable: false;
     readonly when: 'Congress.gov rejected the request as malformed — a bad date range or an identifier with an unexpected shape.';
     readonly recovery: 'Check parameter formats: dates must be ISO 8601 like 2026-05-01T00:00:00Z and identifiers must match their documented shape.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ConfigurationError;
+    readonly reason: 'api_key_rejected';
+    readonly thrownBy: 'service';
+    readonly retryable: false;
+    readonly when: "The api.data.gov gateway rejected the server's configured CONGRESS_API_KEY (missing, invalid, disabled, unauthorized, or unverified); the gateway code is in data.upstreamCode. No change to the call's arguments can fix it.";
+    readonly recovery: 'This is a server configuration problem, not a request problem: the operator must replace CONGRESS_API_KEY with a valid api.data.gov key (https://api.data.gov/signup/) or unset it to fall back to the rate-limited DEMO_KEY, then restart the server.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
     readonly reason: 'upstream_error';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status).';
+    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status) or could not be reached, or the Senate LIS feed failed (5xx, a timeout, or a senate.gov HTTP 403 refusal, which carries retryable: false).';
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Timeout;
     readonly reason: 'upstream_timeout';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'The Congress.gov request deadline expired or the upstream returned an HTTP timeout response.';
+    readonly when: "A Congress.gov request or a congress.gov document fetch timed out or returned an HTTP timeout response, or the call's upstream requests could not finish inside its 50-second budget.";
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;

package/dist/mcp-server/tools/definitions/bill-lookup.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bill-lookup.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/bill-lookup.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AA6DjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4WzB,CAAC"}
+{"version":3,"file":"bill-lookup.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/bill-lookup.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AA6DjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4WzB,CAAC"}

package/dist/mcp-server/tools/definitions/bill-summaries.tool.d.ts

@@ -46,19 +46,26 @@ export declare const billSummariesTool: import("@cyanheads/mcp-ts-core").ToolDef
     readonly retryable: false;
     readonly when: 'Congress.gov rejected the request as malformed — a bad date range or an identifier with an unexpected shape.';
     readonly recovery: 'Check parameter formats: dates must be ISO 8601 like 2026-05-01T00:00:00Z and identifiers must match their documented shape.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ConfigurationError;
+    readonly reason: 'api_key_rejected';
+    readonly thrownBy: 'service';
+    readonly retryable: false;
+    readonly when: "The api.data.gov gateway rejected the server's configured CONGRESS_API_KEY (missing, invalid, disabled, unauthorized, or unverified); the gateway code is in data.upstreamCode. No change to the call's arguments can fix it.";
+    readonly recovery: 'This is a server configuration problem, not a request problem: the operator must replace CONGRESS_API_KEY with a valid api.data.gov key (https://api.data.gov/signup/) or unset it to fall back to the rate-limited DEMO_KEY, then restart the server.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
     readonly reason: 'upstream_error';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status).';
+    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status) or could not be reached, or the Senate LIS feed failed (5xx, a timeout, or a senate.gov HTTP 403 refusal, which carries retryable: false).';
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Timeout;
     readonly reason: 'upstream_timeout';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'The Congress.gov request deadline expired or the upstream returned an HTTP timeout response.';
+    readonly when: "A Congress.gov request or a congress.gov document fetch timed out or returned an HTTP timeout response, or the call's upstream requests could not finish inside its 50-second budget.";
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }], {
     effectiveQuery: z.ZodString;

package/dist/mcp-server/tools/definitions/bill-summaries.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bill-summaries.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/bill-summaries.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAwBjD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmH5B,CAAC"}
+{"version":3,"file":"bill-summaries.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/bill-summaries.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAwBjD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmH5B,CAAC"}

package/dist/mcp-server/tools/definitions/committee-lookup.tool.d.ts

@@ -53,19 +53,26 @@ export declare const committeeLookupTool: import("@cyanheads/mcp-ts-core").ToolD
     readonly retryable: false;
     readonly when: 'Congress.gov rejected the request as malformed — a bad date range or an identifier with an unexpected shape.';
     readonly recovery: 'Check parameter formats: dates must be ISO 8601 like 2026-05-01T00:00:00Z and identifiers must match their documented shape.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ConfigurationError;
+    readonly reason: 'api_key_rejected';
+    readonly thrownBy: 'service';
+    readonly retryable: false;
+    readonly when: "The api.data.gov gateway rejected the server's configured CONGRESS_API_KEY (missing, invalid, disabled, unauthorized, or unverified); the gateway code is in data.upstreamCode. No change to the call's arguments can fix it.";
+    readonly recovery: 'This is a server configuration problem, not a request problem: the operator must replace CONGRESS_API_KEY with a valid api.data.gov key (https://api.data.gov/signup/) or unset it to fall back to the rate-limited DEMO_KEY, then restart the server.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
     readonly reason: 'upstream_error';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status).';
+    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status) or could not be reached, or the Senate LIS feed failed (5xx, a timeout, or a senate.gov HTTP 403 refusal, which carries retryable: false).';
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Timeout;
     readonly reason: 'upstream_timeout';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'The Congress.gov request deadline expired or the upstream returned an HTTP timeout response.';
+    readonly when: "A Congress.gov request or a congress.gov document fetch timed out or returned an HTTP timeout response, or the call's upstream requests could not finish inside its 50-second budget.";
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }], {
     effectiveQuery: z.ZodString;

package/dist/mcp-server/tools/definitions/committee-lookup.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"committee-lookup.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/committee-lookup.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAgHjD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8N9B,CAAC"}
+{"version":3,"file":"committee-lookup.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/committee-lookup.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAgHjD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8N9B,CAAC"}

package/dist/mcp-server/tools/definitions/committee-reports.tool.d.ts

@@ -55,19 +55,26 @@ export declare const committeeReportsTool: import("@cyanheads/mcp-ts-core").Tool
     readonly retryable: false;
     readonly when: 'Congress.gov rejected the request as malformed — a bad date range or an identifier with an unexpected shape.';
     readonly recovery: 'Check parameter formats: dates must be ISO 8601 like 2026-05-01T00:00:00Z and identifiers must match their documented shape.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ConfigurationError;
+    readonly reason: 'api_key_rejected';
+    readonly thrownBy: 'service';
+    readonly retryable: false;
+    readonly when: "The api.data.gov gateway rejected the server's configured CONGRESS_API_KEY (missing, invalid, disabled, unauthorized, or unverified); the gateway code is in data.upstreamCode. No change to the call's arguments can fix it.";
+    readonly recovery: 'This is a server configuration problem, not a request problem: the operator must replace CONGRESS_API_KEY with a valid api.data.gov key (https://api.data.gov/signup/) or unset it to fall back to the rate-limited DEMO_KEY, then restart the server.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
     readonly reason: 'upstream_error';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status).';
+    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status) or could not be reached, or the Senate LIS feed failed (5xx, a timeout, or a senate.gov HTTP 403 refusal, which carries retryable: false).';
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Timeout;
     readonly reason: 'upstream_timeout';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'The Congress.gov request deadline expired or the upstream returned an HTTP timeout response.';
+    readonly when: "A Congress.gov request or a congress.gov document fetch timed out or returned an HTTP timeout response, or the call's upstream requests could not finish inside its 50-second budget.";
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;

package/dist/mcp-server/tools/definitions/committee-reports.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"committee-reports.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/committee-reports.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAkCjD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqL/B,CAAC"}
+{"version":3,"file":"committee-reports.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/committee-reports.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAkCjD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqL/B,CAAC"}

package/dist/mcp-server/tools/definitions/crs-reports.tool.d.ts

@@ -39,19 +39,26 @@ export declare const crsReportsTool: import("@cyanheads/mcp-ts-core").ToolDefini
     readonly retryable: false;
     readonly when: 'Congress.gov rejected the request as malformed — a bad date range or an identifier with an unexpected shape.';
     readonly recovery: 'Check parameter formats: dates must be ISO 8601 like 2026-05-01T00:00:00Z and identifiers must match their documented shape.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ConfigurationError;
+    readonly reason: 'api_key_rejected';
+    readonly thrownBy: 'service';
+    readonly retryable: false;
+    readonly when: "The api.data.gov gateway rejected the server's configured CONGRESS_API_KEY (missing, invalid, disabled, unauthorized, or unverified); the gateway code is in data.upstreamCode. No change to the call's arguments can fix it.";
+    readonly recovery: 'This is a server configuration problem, not a request problem: the operator must replace CONGRESS_API_KEY with a valid api.data.gov key (https://api.data.gov/signup/) or unset it to fall back to the rate-limited DEMO_KEY, then restart the server.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
     readonly reason: 'upstream_error';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status).';
+    readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status) or could not be reached, or the Senate LIS feed failed (5xx, a timeout, or a senate.gov HTTP 403 refusal, which carries retryable: false).';
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Timeout;
     readonly reason: 'upstream_timeout';
     readonly thrownBy: 'service';
     readonly retryable: true;
-    readonly when: 'The Congress.gov request deadline expired or the upstream returned an HTTP timeout response.';
+    readonly when: "A Congress.gov request or a congress.gov document fetch timed out or returned an HTTP timeout response, or the call's upstream requests could not finish inside its 50-second budget.";
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
 }, {
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;

package/dist/mcp-server/tools/definitions/crs-reports.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crs-reports.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/crs-reports.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAcjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0DzB,CAAC"}
+{"version":3,"file":"crs-reports.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/crs-reports.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAcjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0DzB,CAAC"}