@bbradar/mcp 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Release notes
 
+## 0.3.2 — new Activity data, contest awards and dependency security (2026-11-07)
+
+- `find_programs` and `find_hunt_targets` now report the sort direction the API actually applied in `ranking_scope.sort_direction` and `scan.sort_direction`. With no `sort_direction`, the API ranks `first_response` and `time_to_bounty` fastest first (ascending), and these fields previously said `desc`. When the API does not echo a direction, the same rule applies.
+- Fixed Activity, payout, History and analytics results failing in MCP clients that validate structured output against the discovered schema. Those schemas rejected unknown top-level fields, so Status rankings fail validation against an API with `facets` (added 2026-10-13), as do Value pages with `labels` and program payouts with `value_period`. The 21 tools that return one Pro API payload as it is now list these fields and also accept fields the API adds later.
+- `get_activity_rankings` and `get_activity_value` accept `period` (`7d`, `30d` or `90d`) for Value, as the API now does; each period is used only when capabilities advertise it. `24h`, `all_time` and launch cohorts remain local errors. Descriptions cover per-period Value measures and labels, the default landing shortlist named by the page's `labels`, and the 90-day-only signals.
+- `get_program` and `get_program_brief` keep `contest_awards`, the final award allocations of a contest or Huntr challenge, with decimal totals in the contest's own token and a null currency where the platform names none. Pending results stay `null`; other program kinds omit the field. The guide routes finished-contest award questions to `get_program`; a finished contest is readable only there, by exact `platform:handle`, since target reads exclude it. This needs the bbradar-web change that serves awards and finished contests on the API key detail route (`/v1/pro/programs/{program_id}`); before it, the field is absent and finished contests are not found.
+- Updated `@modelcontextprotocol/sdk` to 1.32.2 and `zod` to 4.6.7, fixing the high-severity advisories that failed `npm audit` and the package check (GHSA-22jm-h49p-29qw, GHSA-46jr-4wx8-v453, GHSA-rvq5-wwqv-78pq and GHSA-6prh-2h8m-c8cw in the SDK; GHSA-mrhx-c7xc-m3w5 in zod, which has no 3.x fix), and refreshed patched transitive dependencies (body-parser, fast-uri, hono, `@hono/node-server`, ip-address, qs). Advertised tool fields, defaults and required inputs are unchanged. Zod 4 adds `propertyNames` to record schemas, safe-integer bounds to integers and an RFC 3339 pattern to date-times, and `find_programs.sort_by` stays one flat enum. `updated_since` now rejects date-times without seconds or with an offset lacking its colon, as its `date-time` format always stated.
+- Tool descriptions and the README cover the API's new data: Status `facets`, payout `average_paid` and its sort, Rewards USD display bounds, per-provider Response definitions and windows, program payout facts (`paid_average`, `paid_maximum`, `last_paid_on`, per-severity figures, triage and resolution times, response rate, researcher counts) and `value_period`.
+
+## 0.3.1 — hunt deadlines and target accuracy (2026-10-13)
+
+- Reduced unnecessary upstream target rows for small direct reads while preserving offset/limit semantics and full-page scans for local filters. Added a live STDIO check with fresh prefix comparison and cache diagnostics. Catalog concurrency remains four: smaller-pool trials did not establish a reliable improvement under changing API latency.
+- Fixed target inventory pagination in latest-addition and named-program workflows, added language-filter continuations, and exposed remaining offsets. Named target actions now honor target-type and language filters.
+- Marked bounded scope counts and capped legacy exports as incomplete instead of full inventory totals. Export fallbacks reject upstream filters they cannot preserve. Malformed collection pages now fail explicitly rather than becoming empty successes.
+- Rejected unknown arguments across all tools, respected negotiated aggregate page limits, and corrected SDK version diagnostics with a packaged-server regression check. Added live workflow smoke checks that report aggregate measurements and stop on failure without retries.
+- Reserved catalog, recent-change and target-sampling time within the hunt's existing tool deadline. Slow optional reads no longer consume the entire call; completed catalog pages survive later-page timeouts with explicit incomplete coverage, errors and phase timings.
+- Applied existing hunt VDP exclusion upstream when negotiated, preserving unknown classifications and the local filters. Added a read-only live hunt benchmark with aggregate timings and quota reporting, plus deadline, cancellation, coverage and legacy-API regression fixtures. Retained the four-request catalog limit after live concurrency comparisons showed no reliable gain from six.
+- Rejected Activity version IDs on catalog/feed snapshot inputs and validated required signal periods and payout metric/period combinations before sending requests. Tool descriptions and guides distinguish the two snapshot contracts and preserve user filters after empty or partial results.
+
 ## 0.3.0 — Activity and payout views (2026-10-12)
 
 - Added five Activity tools to the default 30-tool `core` profile: `get_activity_capabilities`, `get_activity_snapshot`, `get_activity_rankings`, `get_program_payouts`, and `get_activity_change_detail`. Rankings cover payouts, Value, scope, rewards, updates, reports, response, status and all changes. The `full` profile also exposes nine per-view aliases.

package/README.md

@@ -116,6 +116,7 @@ Self-Hosted programs use IDs such as `Self-Hosted:program-slug`. They are availa
 
 `search_programs` accepts a `search` value and sends it to the API for indexed server-side filtering. Name resolution uses the same path automatically, avoiding broad page scans for exact or partial program names.
 Use `program_kind: "bounty"`, `"contest"`, or `"challenge"` with `search_programs` or `find_programs` for source-classified program filtering. `find_web3_contests` uses this classification instead of inferring contests from a name or platform.
+`get_program` and `get_program_brief` keep `contest_awards` for a contest or Huntr challenge: the final award allocations its platform publishes (`contest_id`, `currency`, `awarded_total`, `pool_amount`, `awarded_count`, `participants`, `source_url`, `checked_at`, `first_final_at`), or `null` before a final result. Totals are decimal strings in the contest's own token, never USD or a payment record; `currency` is `null` when the platform names none (Huntr). A finished contest with a final result stays readable through `get_program` by exact `platform:handle`, without an opportunity tag; discovery, name resolution and target reads (so also `get_program_brief`) exclude ended contests. The field needs an API whose key-authenticated detail route (`/v1/pro/programs/{program_id}`) serves it; an older API omits it and answers 404 for finished contests.
 The program catalog now includes confirmed paused platform programs. Raw search preserves `program_status` and `is_active`; ranked discovery excludes paused programs so retained scope and historical rewards cannot be presented as huntable. Exact paused-program reads remain available when explicitly requested.
 
 The full tool profile also exposes `search_targets`, a one-request low-level wrapper for reverse search and paginated current target inventory. It supports optional `q`, all API match modes, platform/tag filters, eligibility controls, pages up to the negotiated 500-row limit, and compact or full target output.
@@ -135,6 +136,8 @@ Repository results preserve the API's comparison completeness/method/ancestry ev
 
 `search_programs`, `search_targets`, `get_recent_changes`, and `get_repository_changes` accept the API's optional stable `snapshot` token. Send `snapshot: "start"` on page 1 and reuse the returned `meta.snapshot` with identical filters until `meta.snapshot_expires_at`. Snapshot responses bypass the local TTL cache, and an expired snapshot 410 is not mistaken for an expired change-feed cursor. Snapshot creation receives a 60-second minimum request timeout because it performs consistency work and can be materially slower; the fast `find_hunt_targets` workflow intentionally keeps live indexed paging and the ordinary configured timeout.
 
+Catalog and feed snapshot tokens have at most 32 characters. `find_programs` uses that same contract. The 64-character version ID from `get_activity_snapshot` binds only Activity capabilities, rankings, event details and program payouts; do not pass it to catalog discovery.
+
 ### Activity and payouts
 
 Use `get_activity_capabilities` before choosing a ranking. Its versioned views give
@@ -153,7 +156,8 @@ silently replace its period or basis.
 | `get_activity_change_detail` | One bounded page of an exact Activity event's before/after items |
 
 `get_activity_rankings` takes `tab`: `payouts` (reported or tracked, the two bases
-kept separate), `value` (frozen Value map and label-specific shortlists),
+kept separate), `value` (frozen Value map and label-specific shortlists for a 7, 30
+or 90-day period),
 `scope`, `rewards`, `updates`, `reports`, `response`, `status` (lifecycle events;
 first seen is not a launch date) or `all_changes` (catalog events, including
 eligible events for departed programs). Each tab accepts only its own inputs:
@@ -174,9 +178,30 @@ An API that does not advertise the filter is told so before any request.
 
 Ranking pages omit the capabilities document the API repeats on every page; read it
 once with `get_activity_capabilities`. When a tab has no enabled default view the
-empty page carries that tab's `available_views` instead.
-
-`tab: "value"` has no period input. With `include_map: true` its `points` cover the
+empty page carries that tab's `available_views` instead. Status pages add `facets`:
+event counts per `change_type` and `current_status` for the period and filters, each
+counted under every other filter but not its own selection, with zero counts omitted.
+
+Payout rows also carry `average_paid`: the platform's own current average payment
+(an exact mean, or HackerOne's 45th to 55th percentile range) with its
+`source_label`, `period`, native currency and USD conversion. It is the same in every
+period, and `sort: "average_paid"` ranks it where capabilities advertise it. Rewards
+rows add `minimum_usd`/`maximum_usd` to `before`/`after` at the version's current
+quotes for display; the change percentage still compares native maxima. Response
+cells keep each provider's definition, label and window (`first_response_label`,
+`first_response_window`, `first_response_precision`, `time_to_bounty_window`), and
+duration sorts (`first_response`, `time_to_bounty`) rank fastest first when
+`direction` is omitted.
+
+`tab: "value"` takes `period` `7d`, `30d` or `90d`, each only once
+`get_activity_capabilities` advertises it: report volume covers that period, while
+payout per processed report is lifetime. Rows and points carry the period's count and
+percentile in `value`; `signals` keep the lifetime and 90-day figures. Without a
+period, a request naming `labels` or `sort` means 90 days, and a bare request opens
+the advertised default view, which can be a label shortlist: the page's `labels`
+names the list applied (empty for the map's programs). High value, Popular and Low
+per report exist in each period; Pays near top, No payouts seen and processed versus
+received exist only at 90 days. With `include_map: true` its `points` cover the
 full filtered map population from the same snapshot (up to 5,000); by default the
 map is replaced by `map_points_omitted` with its count, because thousands of points
 rarely help a text answer. `rows` are a separately paginated shortlist. Percentiles stay frozen within their original platform cohorts after
@@ -187,8 +212,14 @@ rejected rather than replaced.
 
 Rankings and `get_program_payouts` return server-owned `signals`, `labels` and
 `label_details`, including explanations and destinations. Program detail also
-returns `value_points` for same-platform peers when called with `include_map: true`
-(otherwise `map_points_omitted` gives their count). “Last payout seen” describes an
+returns `value_points` for same-platform peers in the Value period named by
+`value_period` when called with `include_map: true` (otherwise `map_points_omitted`
+gives their count). Its `facts` also carry each platform's own published figures,
+each with its `measure`, `unit`, `period` and `source_label`: `paid_average`,
+`paid_maximum` and `last_paid_on`, HackerOne's 90-day `paid_average_<severity>` and
+lifetime `severity_reports_<severity>`, triage and resolution times, PatchDay's
+response rate and researcher counts. They are program-detail facts with no Activity
+column or sort; keep each definition rather than comparing platforms as one measure. “Last payout seen” describes an
 observed counter increase, never a payment date. “Pays near top” is the platform's
 top-quarter rule: retain the actual amount/percentage in the explanation. Processed
 vs received can exceed 100% and does not measure response speed. Never recalculate
@@ -236,8 +267,10 @@ Reports and resolved counters support `7d`, `30d`, `90d`, `all_time`, and API-on
 `24h` where enabled. All-time uses the fresh lifetime counter; it has no Previous
 or Change. Finite report comparisons retain the same basis within each program;
 report volume does not establish researcher competition. Scope, Rewards, Updates,
-Status and All changes support only `7d`, `30d` and `90d`. Response counts retain
-the provider's term; time to bounty measures award timing, not settlement. Label
+Status and All changes support only `7d`, `30d` and `90d`. Response publishes only
+`7d` and `30d` until resolved counters hold 90 days of history; use the periods
+capabilities advertise. Response counts retain the provider's term (resolved,
+accepted, paid or rewarded); time to bounty measures award timing, not settlement. Label
 filters must come from current capabilities, and unsupported labels remain errors.
 
 Use exact `platform:handle` identities for `get_program_payouts`; slash-containing
@@ -246,6 +279,11 @@ definitions and source timestamps remain intact in structured output. Human
 summaries should show the available numbers and units, keeping internal collection
 and completeness metadata in the structured result.
 
+Tools that return one Pro API payload as it is (the Activity, payout, History and
+analytics tools) list its known fields in their output schemas and also accept new
+top-level fields. Clients validate structured results against the schema they
+discovered, so a field the API adds later reaches them instead of failing the call.
+
 `find_programs` and `find_hunt_targets` accept combined Activity predicates
 (`search_programs` and `get_opportunities` reject them; use `find_programs`, with one
 `opportunity_levels` entry for a tier). The API applies them together before
@@ -253,7 +291,9 @@ pagination, preserving one global ordering and one stable snapshot. For example,
 `{"payout_period":"30d","payout_metric":"payout_increase","payout_min":1000,"reports_period":"7d","reports_max":10,"sort_by":"payout_amount","sort_direction":"desc"}`
 to combine measured payouts in the last 30 days with report activity in the last
 7 days. Add `snapshot: "start"` on the first page and reuse `meta.snapshot` with
-identical filters. The default order remains `updated` descending. Bounds sorts
+identical filters. The default order remains `updated` descending; an omitted
+`sort_direction` for `first_response` or `time_to_bounty` means ascending (fastest
+first), and `ranking_scope.sort_direction` reports the order applied. Bounds sorts
 require `proven_bounds`: `payout_lower_bound` descends and `payout_upper_bound`
 ascends. `payout_positive: false` requires an exact observed zero; omit it when
 both zero and positive payers should qualify.
@@ -344,6 +384,22 @@ Already-retired historical events cannot be reconstructed. `get_program_targets`
 follows upstream API pages until it can satisfy the requested offset/limit or the
 inventory ends. Missing public scope is treated as out of scope.
 
+Target lists expose `meta.has_more` and `meta.next_offset`; repeat the same filters
+with that offset to continue. `language_tags` applies while scanning pages, so
+sparse matches do not skip eligible targets. Named target actions honor their
+target-type and language filters. `get_latest_added_targets` also pages its optional
+inventory and returns `full_targets_next_offset` for `get_program_targets`.
+Scope summaries and breakdowns label sampled counts with `count_scope` and
+`possibly_incomplete`; unknown full filtered totals are omitted. Legacy export
+fallbacks disclose their cap and reject filters whose upstream semantics they
+cannot preserve. All tools reject unknown arguments, and malformed collection
+responses return errors instead of claiming the inventory is empty.
+
+Small direct target reads request only the prefix needed for their offset and limit,
+up to the negotiated page size, instead of always loading a 500-row page. Local
+scope and language post-filters retain full pages to find sparse matches. This
+reduces excess transfer and processing while preserving fresh reads and row offsets.
+
 Cursors are memory-only by default. Set `BBRADAR_MCP_CURSOR_STATE_PATH` to opt into restart-safe cursor persistence. The state file contains only endpoint-prefixed SHA-256 filter hashes and non-negative numeric IDs—never raw filters, API responses, program or target records, credentials, or authorization headers.
 
 For cacheable responses, large target and change collections return at most 50 inline records by default; the remainder is held in a bounded, ten-minute continuation resource. Private or `no-store` pages stay in the current structured result and are never put in a reusable continuation. Compact tool text keeps model context small.
@@ -379,6 +435,24 @@ Call `get_mcp_status` to inspect cache and stale-hit rates, circuit states, curs
 
 Run `npm run benchmark` for deterministic local benchmarks. They report request and byte counts, model-context bytes, latency percentiles, and memory under representative History and analytics concurrency. Fixture timings are separate from live API latency.
 
+With `BBRADAR_API_KEY` already configured, run `npm run build` then `node benchmark/live-hunt.mjs` for one authenticated all-platform Web2 hunt (domain/API, $5,000 maximum bounty, at least three eligible and five total targets, 15 results). It reports aggregate phase timings, request counts, quota and sampled coverage without printing the key or program/target records. This consumes live API quota and makes no automatic retries. Live catalog updates can change rows between pages; signatures help distinguish result changes from timing changes.
+
+`node benchmark/live-api-check.mjs` checks negotiated capabilities, discovery,
+all nine Activity tabs, program and target reads, payouts, History, daily analytics,
+feeds, combined filters and the same hunt. It emits aggregate measurements and
+stops at the first failure. An optional section (`activity`, `programs`, `analytics`,
+`feeds`, or `hunt`) runs only that workflow and its prerequisites, so independent
+checks can continue without repeating successful sections. These are live reads
+and consume quota; a smoke pass is not an uptime or complete-catalog guarantee.
+
+`node benchmark/live-stdio.mjs` performs the original hunt through the actual
+STDIO server entry point using the configured key, then compares a fresh small
+target page with the prefix of a fresh wider page. Use `targets` to run the target
+check independently. It reports cache activity, timings and counts, never target
+identifiers. Partial hunts fail the benchmark instead of counting as speed gains.
+`live-hunt.mjs --catalog-concurrency=2` can test a lower catalog request cap;
+inspect both timings and coverage before adopting a concurrency change.
+
 Maintainers can compare the working tree against a committed revision with `npm run build` followed by `node --expose-gc benchmark/compare-revisions.mjs HEAD`. This uses the same fixtures and alternating samples for both revisions, reports discovery and result sizes, and measures repeated private reads separately from cacheable reads. It requires the repository and development dependencies.
 
 Run `npm run test:package` to pack the release, install its production dependencies in a temporary directory, audit them, and exercise the packaged STDIO server. CI runs the checks on Node 20, 22, and 24.
@@ -393,6 +467,12 @@ Use `find_hunt_targets` as the default one-call path when a request combines goo
 
 `find_hunt_targets` supports arbitrary platform inclusion/exclusion, scope/target/language filters, reward and breadth thresholds, Web2/Web3 modes, target-intelligence filters, freshness windows, `free_submission_only`, and balanced/reward/scope/freshness/competition ranking. Activity inputs such as `payout_period: "30d"` with `payout_positive: true`, or `scope_period: "30d"` with `scope_added_min: 1`, first narrow its candidates on the server in global order; the remaining filters and `ranking_mode` then apply locally, and `scan` reports how much of the server result was examined. Unknown inputs are rejected rather than ignored. It suppresses bulk `bbradar://` resource links while preserving each program's public BBRadar and platform URLs, preventing large shortlists from flooding model context.
 
+The hunt reserves time within the configured tool deadline: catalog discovery uses at most 60%, optional recent-change queries 30% in parallel, and target sampling finishes by 90%, leaving time to return the result. With the default 30 seconds, those bounds are 18, 9 and 27 seconds. A stalled later catalog page preserves completed pages; Activity scans retain only their completed ordered prefix. A failed first catalog page remains an error. Partial reads include `errors`, warnings, `meta.partial_success`, `result_guidance.coverage_incomplete` and `meta.phase_timing`. Missing enrichment is unavailable evidence. Keep the user's platform scope and thresholds; a sampled change feed cannot identify the complete supported platform set.
+
+Legacy catalog hunts apply their existing VDP exclusion upstream when the API advertises that mode, then retain the local filters. Programs with unknown classifications and positive rewards remain eligible. Older APIs keep local exclusion. Catalog paging retains its four-request limit within the configured global pool; Activity scans keep their separate two-request limit.
+
+Combined Activity filters need independent periods. `change_category` requires `updates_period`; filtering additions with `scope_period` and `scope_added_min` alone needs no category. `payout_total` requires `payout_period: "all_time"`; use `payout_increase` for tracked 24h/7d/30d/90d changes, or an enabled `payout_native_90d` comparison with 90d for provider-reported values. Invalid combinations fail locally with guidance. An empty valid result does not authorize changing requested thresholds.
+
 ```json
 {
   "platforms": ["Immunefi", "HackenProof", "BugCrowd", "YesWeHack"],

package/benchmark/live-api-check.mjs

@@ -0,0 +1,126 @@
+// Read-only production smoke check. Requires BBRADAR_API_KEY; emits aggregate
+// measurements only and stops at the first failed call without retrying.
+// Usage: node benchmark/live-api-check.mjs [all|activity|programs|analytics|feeds|hunt]
+import assert from "node:assert/strict";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { BBRadarClient } from "../dist/bbradarClient.js";
+import { loadConfig } from "../dist/config.js";
+import { createBbradarServer } from "../dist/server.js";
+
+const config = loadConfig();
+config.toolProfile = "core";
+const section = process.argv[2] ?? "all";
+assert.ok(["all", "activity", "programs", "analytics", "feeds", "hunt"].includes(section), "Use all, activity, programs, analytics, feeds, or hunt.");
+const enabled = name => section === "all" || section === name;
+const upstream = new BBRadarClient(config);
+const observations = [];
+const report = { measured_at: new Date().toISOString(), fixture: false, section, observations };
+let server, client;
+async function call(name, args = {}) {
+  const before = upstream.diagnostics().upstream_requests.actual_requests;
+  const result = await client.callTool({ name, arguments: args });
+  const data = result.structuredContent;
+  observations.push({ tool: name, tab: args.tab, success: !result.isError,
+    status: data?.error?.status,
+    error: data?.error?.message?.replaceAll(config.apiKey, "[redacted]"),
+    duration_ms: data?.mcp_timing?.duration_ms,
+    requests: upstream.diagnostics().upstream_requests.actual_requests - before,
+    rows: (data?.rows ?? data?.programs ?? data?.targets ?? data?.changes ?? data?.series ?? data?.matches)?.length,
+    no_store: data?.cache?.no_store, partial_success: data?.meta?.partial_success,
+    coverage_incomplete: data?.result_guidance?.coverage_incomplete,
+    phase_timing: data?.meta?.phase_timing });
+  if (result.isError) throw new Error(`${name} failed with status ${data?.error?.status ?? "unknown"}`);
+  return data;
+}
+
+try {
+  await upstream.negotiateCapabilities();
+  const contract = upstream.capabilitySnapshot();
+  assert.equal(contract.status, "negotiated");
+  report.contract_version = contract.contract.contract_version;
+  report.api_endpoints = Object.keys(contract.contract.endpoints).sort();
+  server = createBbradarServer(upstream, config);
+  client = new Client({ name: "bbradar-live-check", version: "1" });
+  const [a, b] = InMemoryTransport.createLinkedPair();
+  await Promise.all([client.connect(a), server.connect(b)]);
+  const discovery = await client.listTools();
+  report.core_tool_count = discovery.tools.length;
+  report.discovery_bytes = Buffer.byteLength(JSON.stringify(discovery));
+  const status = await call("get_mcp_status");
+  report.server_version = status.status.server_version;
+  report.sdk_version = status.status.sdk_version;
+  await call("get_bbradar_guide");
+  let snapshot;
+  if (enabled("activity") || enabled("programs")) {
+    const version = await call("get_activity_snapshot");
+    snapshot = version.snapshot_id;
+  }
+  if (enabled("activity")) {
+    const capabilities = await call("get_activity_capabilities", { snapshot });
+    for (const tab of capabilities.tabs) {
+      // Let the server select its advertised default; an unqualified default
+      // legitimately returns no rows plus available_views, never an invented view.
+      const page = await call("get_activity_rankings", { tab: tab.id, snapshot, limit: 1 });
+      assert.equal(page.tab, tab.id);
+      assert.equal(page.meta.snapshot_id, snapshot);
+      assert.equal(page.cache.no_store, true);
+      assert.ok(Array.isArray(page.rows));
+      if (page.sort === null) assert.ok(Array.isArray(page.available_views));
+    }
+  }
+  let program;
+  if (enabled("programs") || enabled("analytics")) {
+    const catalog = await call("search_programs", { page_size: 5 });
+    program = catalog.programs.find(row => row.platform !== "Self-Hosted");
+    assert.ok(program?.id, "The bounded live catalog had no program for the detail checks.");
+  }
+  if (enabled("programs")) {
+    await call("get_program", { program_id: program.id });
+    await call("get_program_targets", { program_id: program.id, limit: 2 });
+    await call("get_program_payouts", { program_id: program.id, snapshot });
+    await call("get_program_activity", { program_id: program.id });
+    await call("get_program_history", { program_id: program.id, limit: 1 });
+    await call("get_history_changes", { limit: 1 });
+  }
+  if (enabled("analytics")) {
+    await call("get_analytics_platform_series", { platform: program.platform, limit: 1 });
+    await call("get_analytics_program_detail", { program_id: program.id, limit: 1 });
+    await call("get_analytics_program_activity", { limit: 1 });
+  }
+  if (enabled("feeds")) {
+    await call("get_recent_changes", { page_size: 1 });
+    await call("get_repository_changes", { page_size: 1, include_targets: false });
+    await call("get_opportunities", { level: "elite", page_size: 1 });
+    const combined = await call("find_programs", {
+      payout_period: "30d", payout_positive: true, require_bounty: true, max_pages: 1, max_results: 1
+    });
+    assert.ok(combined.scan);
+  }
+  if (enabled("hunt")) {
+    const hunt = await call("find_hunt_targets", {
+      surface_mode: "web2", target_types: ["domain", "api"], require_bounty: true,
+      min_bounty_max: 5000, min_eligible_targets: 3, min_total_targets: 5,
+      include_recent_changes: true, include_unknown_report_count: true,
+      recent_target_days: 90, max_results: 15, targets_per_result: 3,
+      ranking_mode: "balanced", upstream_request_budget: 50
+    });
+    assert.ok(hunt.matches.length > 0);
+    assert.equal(hunt.filters.min_bounty_max, 5000);
+    assert.equal(hunt.filters.surface_mode, "web2");
+    assert.ok(hunt.upstream_budget.used <= 50);
+    report.hunt = { returned: hunt.matches.length, target_samples: hunt.matches.reduce((sum, row) => sum + row.target_samples.length, 0),
+      ranking_scope: hunt.ranking_scope, upstream_budget: hunt.upstream_budget, partial_success: hunt.meta.partial_success };
+    if (hunt.meta.partial_success) process.exitCode = 1;
+  }
+} catch (error) {
+  report.failure = String(error.message).replaceAll(config.apiKey, "[redacted]");
+  process.exitCode = 1;
+} finally {
+  await client?.close();
+  await server?.close();
+  report.requests = upstream.diagnostics().upstream_requests.actual_requests;
+  report.concurrency = upstream.diagnostics().request_concurrency;
+  report.request_window = upstream.diagnostics().upstream_request_window;
+  console.log(JSON.stringify(report, null, 2));
+}

package/benchmark/live-hunt.mjs

@@ -0,0 +1,105 @@
+// One authenticated read-only hunt. Only aggregate measurements reach stdout;
+// credentials and program/target records are never written to disk.
+// With BBRADAR_API_KEY configured: node benchmark/live-hunt.mjs
+// Optional experiment: node benchmark/live-hunt.mjs --catalog-concurrency=2
+// This only lowers catalog concurrency; it never changes filters or page counts.
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { BBRadarClient } from "../dist/bbradarClient.js";
+import { loadConfig } from "../dist/config.js";
+import { createBbradarServer } from "../dist/server.js";
+
+const args = {
+  surface_mode: "web2", target_types: ["domain", "api"], require_bounty: true,
+  min_bounty_max: 5000, min_eligible_targets: 3, min_total_targets: 5,
+  include_recent_changes: true, include_unknown_report_count: true,
+  recent_target_days: 90, max_results: 15, targets_per_result: 3,
+  ranking_mode: "balanced", upstream_request_budget: 50
+};
+const config = loadConfig();
+const catalogOption = process.argv.slice(2);
+assert.ok(catalogOption.length <= 1 && (!catalogOption.length || /^--catalog-concurrency=[1-4]$/.test(catalogOption[0])),
+  "Use --catalog-concurrency=1, 2, 3 or 4, or omit it for the server default.");
+const catalogConcurrency = catalogOption.length ? Number(catalogOption[0].split("=")[1]) : Number.POSITIVE_INFINITY;
+let activeCatalog = 0;
+let peakCatalog = 0;
+const catalogWaiters = [];
+async function acquireCatalog() {
+  if (activeCatalog < catalogConcurrency) {
+    activeCatalog += 1;
+    peakCatalog = Math.max(peakCatalog, activeCatalog);
+    return;
+  }
+  await new Promise(resolve => catalogWaiters.push(resolve));
+}
+function releaseCatalog() {
+  const next = catalogWaiters.shift();
+  if (next) next(); else activeCatalog -= 1;
+}
+const upstream = new BBRadarClient(config);
+const request = upstream.request.bind(upstream);
+const redact = value => String(value).replaceAll(config.apiKey, "[redacted]");
+let timings = [];
+let catalogIds = new Set();
+upstream.request = async options => {
+  const start = performance.now();
+  const endpoint = options.path.replace(/\/programs\/.+\/targets$/, "/programs/:program_id/targets");
+  const isCatalog = options.path === "/pro/programs";
+  if (isCatalog) await acquireCatalog();
+  try {
+    const result = await request(options);
+    for (const program of result.data?.programs ?? []) catalogIds.add(program.id);
+    timings.push({ endpoint, page: options.query?.page, elapsed_ms: Math.round(performance.now() - start),
+      status: result.status, cached: result.cached, coalesced: result.coalesced,
+      rows: result.data?.programs?.length ?? result.data?.results?.length ?? result.data?.targets?.length });
+    return result;
+  } catch (error) {
+    timings.push({ endpoint, page: options.query?.page, elapsed_ms: Math.round(performance.now() - start),
+      status: error.status ?? null, error: redact(error.message) });
+    throw error;
+  } finally {
+    if (isCatalog) releaseCatalog();
+  }
+};
+const hash = values => createHash("sha256").update(JSON.stringify([...values].sort())).digest("hex");
+
+try {
+  await upstream.negotiateCapabilities();
+  const server = createBbradarServer(upstream, config);
+  const client = new Client({ name: "bbradar-live-benchmark", version: "1" });
+  const [a, b] = InMemoryTransport.createLinkedPair();
+  await Promise.all([client.connect(a), server.connect(b)]);
+  try {
+    timings = [];
+    catalogIds = new Set();
+    const before = upstream.diagnostics().upstream_requests.actual_requests;
+    const result = await client.callTool({ name: "find_hunt_targets", arguments: args });
+    const data = result.structuredContent;
+    const matches = data?.matches ?? [];
+    const observation = {
+      concurrency: config.maxConcurrentRequests,
+      catalog_concurrency_cap: Number.isFinite(catalogConcurrency) ? catalogConcurrency : "server_default",
+      catalog_request_peak: peakCatalog, is_error: result.isError ?? false,
+      error: data?.error ? { status: data.error.status, message: redact(data.error.message) } : undefined,
+      timing: data?.mcp_timing, phase_timing: data?.meta?.phase_timing,
+      returned: matches.length, target_samples: matches.reduce((count, match) => count + match.target_samples.length, 0),
+      programs_without_target_samples: matches.filter(match => !match.target_samples.length).length,
+      partial_success: data?.meta?.partial_success, coverage_incomplete: data?.result_guidance?.coverage_incomplete,
+      ranking_scope: data?.ranking_scope,
+      upstream_budget: data?.upstream_budget, actual_requests: upstream.diagnostics().upstream_requests.actual_requests - before,
+      catalog_rows: catalogIds.size, catalog_signature: hash(catalogIds),
+      shortlist_signature: hash(matches.map(match => match.program.id)),
+      errors: data?.errors?.map(error => ({ status: error.status, message: redact(error.message) })),
+      timings
+    };
+    if (result.isError || data?.meta?.partial_success) process.exitCode = 1;
+    console.log(JSON.stringify({ fixture: false, measured_at: new Date().toISOString(), arguments: args, observations: [observation],
+      quota: upstream.diagnostics().upstream_rate_limit,
+      request_window: upstream.diagnostics().upstream_request_window }, null, 2));
+  } finally { await client.close(); await server.close(); }
+} catch (error) {
+  console.error(JSON.stringify({ status: error.status ?? null, message: redact(error.message) }));
+  process.exitCode = 1;
+}

package/benchmark/live-stdio.mjs

@@ -0,0 +1,80 @@
+// Authenticated production smoke check through the actual STDIO entry point.
+// Emits aggregates only; never writes credentials or program/target records.
+// node benchmark/live-stdio.mjs [hunt|targets]
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { loadConfig } from "../dist/config.js";
+
+const config = loadConfig();
+const mode = process.argv[2] ?? "hunt";
+assert.ok(["hunt", "targets"].includes(mode), "Use hunt or targets.");
+const client = new Client({ name: "bbradar-live-stdio", version: "1" });
+const transport = new StdioClientTransport({ command: process.execPath,
+  args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))], stderr: "pipe",
+  env: { BBRADAR_API_KEY: config.apiKey, BBRADAR_API_BASE_URL: config.apiBaseUrl,
+    BBRADAR_MCP_TOOL_PROFILE: "core", BBRADAR_MCP_VALIDATE_ON_STARTUP: "true" } });
+const report = { measured_at: new Date().toISOString(), fixture: false, transport: "stdio", mode };
+async function call(name, args = {}) {
+  const result = await client.callTool({ name, arguments: args });
+  if (result.isError) throw new Error(`${name}: ${result.structuredContent?.error?.message ?? "MCP call failed"}`);
+  return result.structuredContent;
+}
+try {
+  await client.connect(transport);
+  const tools = await client.listTools();
+  report.core_tools = tools.tools.length;
+  const before = (await call("get_mcp_status")).status.client;
+  assert.equal(before.capability_negotiation.status, "negotiated");
+  let programs;
+  if (mode === "hunt") {
+    const hunt = await call("find_hunt_targets", {
+      surface_mode: "web2", target_types: ["domain", "api"], require_bounty: true,
+      min_bounty_max: 5000, min_eligible_targets: 3, min_total_targets: 5,
+      include_recent_changes: true, include_unknown_report_count: true,
+      recent_target_days: 90, max_results: 15, targets_per_result: 3,
+      ranking_mode: "balanced", upstream_request_budget: 50
+    });
+    report.hunt = { duration_ms: hunt.mcp_timing.duration_ms, phase_timing: hunt.meta.phase_timing,
+      programs: hunt.matches.length, target_samples: hunt.matches.reduce((n, row) => n + row.target_samples.length, 0),
+      upstream_requests: hunt.upstream_budget.used, partial_success: hunt.meta.partial_success,
+      ranking_scope: hunt.ranking_scope, catalog_pages_read: hunt.source_requests.filter(row => row.source === "programs").length,
+      errors: hunt.errors?.map(error => ({ status: error.status, message: error.message?.replaceAll(config.apiKey, "[redacted]") })),
+      shortlist_signature: createHash("sha256").update(JSON.stringify(hunt.matches.map(row => row.program.id).sort())).digest("hex") };
+    assert.equal(hunt.meta.partial_success, false, "The hunt returned incomplete work; do not count it as a successful performance run.");
+    assert.ok(hunt.matches.length > 0);
+    programs = hunt.matches.map(row => row.program);
+  } else {
+    programs = (await call("search_programs", { page_size: 10 })).programs;
+  }
+  // Compare the requested prefix with a fresh wider read. A live source change
+  // remains a failed comparison, never an excuse to substitute old data.
+  const selected = [...programs].sort((a, b) => (b.scope_summary?.target_counts?.eligible_for_bounty ?? 0)
+    - (a.scope_summary?.target_counts?.eligible_for_bounty ?? 0))[0];
+  assert.ok(selected?.id, "The bounded catalog returned no target candidate.");
+  const args = { program_id: selected.id, output_mode: "identifiers" };
+  const wide = await call("get_program_targets", { ...args, limit: 500 });
+  const small = await call("get_program_targets", { ...args, limit: 3 });
+  assert.ok(wide.targets.length > 0);
+  assert.ok(JSON.stringify(wide.targets.slice(0, 3)) === JSON.stringify(small.targets), "Fresh target prefixes differ; inspect source drift before claiming equivalence.");
+  assert.equal(wide.cache.no_store, true);
+  assert.equal(small.cache.no_store, true);
+  report.target_prefix = { equal: true, wide_read_rows: wide.targets.length, small_read_rows: small.targets.length,
+    wide_read_ms: wide.mcp_timing.duration_ms, small_read_ms: small.mcp_timing.duration_ms,
+    small_read_has_more: small.meta.has_more, small_read_next_offset: small.meta.next_offset, both_no_store: true };
+  const after = (await call("get_mcp_status")).status.client;
+  report.upstream_requests = after.upstream_requests.actual_requests - before.upstream_requests.actual_requests;
+  report.response_cache = after.response_cache;
+  report.request_window = after.upstream_request_window;
+  assert.equal(after.request_concurrency.active, 0);
+  assert.equal(after.request_concurrency.queued, 0);
+} catch (error) {
+  report.failure = String(error.message).replaceAll(config.apiKey, "[redacted]");
+  process.exitCode = 1;
+} finally {
+  await client.close();
+  await transport.close();
+  console.log(JSON.stringify(report, null, 2));
+}

package/dist/activityContract.d.ts

@@ -1,2 +1,4 @@
 /** Catalog metadata stays available when Activity computation is disabled. */
 export declare function requiresActivityQuery(input?: Record<string, unknown>): boolean;
+/** Validate dependencies without supplying or changing the user's periods. */
+export declare function validateActivityCatalogInput(input: Record<string, unknown>): void;

package/dist/activityContract.js

@@ -12,4 +12,36 @@ export function requiresActivityQuery(input = {}) {
     return Object.entries(input).some(([key, value]) => value !== undefined && value !== null
         && (key === "sort_by" ? value !== "updated" : ACTIVITY_FILTERS.has(key)));
 }
+/** Validate dependencies without supplying or changing the user's periods. */
+export function validateActivityCatalogInput(input) {
+    const requirements = {
+        scope: ["scope_added_min", "scope_removed_min", "scope_net_min", "scope_net_max"],
+        reward: ["reward_change", "reward_change_min_pct"],
+        updates: ["active_days_min", "changes_min", "change_category"],
+        reports: ["reports_min", "reports_max", "reports_change", "reports_change_min_pct"],
+        resolved: ["resolved_min"], status: ["status_change"],
+        payout: ["payout_min", "payout_max", "payout_metric", "payout_activity", "payout_positive", "payout_precision"]
+    };
+    const sortPeriods = {
+        payout_amount: "payout", payout_lower_bound: "payout", payout_upper_bound: "payout",
+        scope_added: "scope", scope_net: "scope", reward_change: "reward", active_days: "updates",
+        last_change: "updates", reports: "reports", reports_change: "reports", resolved: "resolved"
+    };
+    for (const [prefix, keys] of Object.entries(requirements)) {
+        const signal = keys.find((key) => input[key] !== undefined);
+        if ((signal || sortPeriods[String(input.sort_by)] === prefix) && input[`${prefix}_period`] === undefined) {
+            throw new Error(`Specify ${prefix}_period for ${signal ?? `sort_by=${String(input.sort_by)}`}. Periods are never inferred from another signal.`);
+        }
+    }
+    const period = input.payout_period;
+    const metric = input.payout_metric ?? (period === "all_time" ? "payout_total" : "payout_increase");
+    if (period !== undefined && ((metric === "payout_total") !== (period === "all_time")
+        || (metric === "payout_native_90d" && period !== "90d"))) {
+        throw new Error("Payout metric and period are incompatible: payout_total requires all_time; payout_increase uses 24h, 7d, 30d or 90d; payout_native_90d requires 90d. Keep the requested period and choose its supported metric.");
+    }
+    if (input.payout_activity !== undefined && (metric !== "payout_increase"
+        || (input.payout_activity !== "increase" && period !== "30d"))) {
+        throw new Error("payout_activity requires payout_increase; no_increase and lower require payout_period=30d.");
+    }
+}
 //# sourceMappingURL=activityContract.js.map

package/dist/activityContract.js.map

@@ -1 +1 @@
-{"version":3,"file":"activityContract.js","sourceRoot":"","sources":["../src/activityContract.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY;IACnG,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,iBAAiB,EAAE,mBAAmB;IAC5F,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB;IAC3F,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,gBAAgB;IACvF,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,iBAAiB;IAC3F,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,0BAA0B;IACrF,0BAA0B,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB;CAClG,CAAC,CAAC;AAEH,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,QAAiC,EAAE;IACvE,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;WACpF,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"activityContract.js","sourceRoot":"","sources":["../src/activityContract.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY;IACnG,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,iBAAiB,EAAE,mBAAmB;IAC5F,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB;IAC3F,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,gBAAgB;IACvF,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,iBAAiB;IAC3F,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,0BAA0B;IACrF,0BAA0B,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB;CAClG,CAAC,CAAC;AAEH,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,QAAiC,EAAE;IACvE,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;WACpF,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,4BAA4B,CAAC,KAA8B;IACzE,MAAM,YAAY,GAA6B;QAC7C,KAAK,EAAE,CAAC,iBAAiB,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,CAAC;QACjF,MAAM,EAAE,CAAC,eAAe,EAAE,uBAAuB,CAAC;QAClD,OAAO,EAAE,CAAC,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,CAAC;QAC9D,OAAO,EAAE,CAAC,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,wBAAwB,CAAC;QACnF,QAAQ,EAAE,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC,eAAe,CAAC;QACrD,MAAM,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,kBAAkB,CAAC;KAChH,CAAC;IACF,MAAM,WAAW,GAA2B;QAC1C,aAAa,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,QAAQ;QACnF,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS;QACzF,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU;KAC5F,CAAC;IACF,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,MAAM,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;YACzG,MAAM,IAAI,KAAK,CAAC,WAAW,MAAM,eAAe,MAAM,IAAI,WAAW,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,mDAAmD,CAAC,CAAC;QACnJ,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACnG,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,cAAc,CAAC,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC;WAC7E,CAAC,MAAM,KAAK,mBAAmB,IAAI,MAAM,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,iNAAiN,CAAC,CAAC;IACrO,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,IAAI,CAAC,MAAM,KAAK,iBAAiB;WACjE,CAAC,KAAK,CAAC,eAAe,KAAK,UAAU,IAAI,MAAM,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,4FAA4F,CAAC,CAAC;IAChH,CAAC;AACH,CAAC"}

package/dist/bbradarClient.d.ts

@@ -10,6 +10,7 @@ export type ApiRequestOptions = {
     staleWhileRevalidateMs?: number;
     timeoutMs?: number;
     signal?: AbortSignal;
+    expectedArray?: "programs" | "targets" | "results";
 };
 export type ApiReadControls = Pick<ApiRequestOptions, "cache" | "coalesce" | "timeoutMs" | "signal">;
 export type ApiResult<T> = {
@@ -73,7 +74,10 @@ export declare class BBRadarClient {
     private capabilityNegotiation;
     private capabilityState;
     constructor(config: ServerConfig);
-    withRequestContext<T>(signal: AbortSignal, callback: () => T | Promise<T>, snapshotStart?: boolean): Promise<T>;
+    withRequestContext<T>(signal: AbortSignal, callback: () => T | Promise<T>, snapshotStart?: boolean, timeoutMs?: number): Promise<T>;
+    /** Give one aggregate stage a shorter budget without extending its parent. */
+    withRequestTimeout<T>(timeoutMs: number, callback: () => T | Promise<T>): Promise<T>;
+    throwIfRequestAborted(): void;
     diagnostics(): {
         response_cache: {
             entries: number;