@bbradar/mcp 0.2.6 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Release notes
 
+## 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.
+- Each ranking reads one bounded server page. Dynamic capabilities describe eligible period, basis, precision, sort and direction combinations; unsupported explicit views remain errors without period substitution.
+- Rankings, capabilities and program payouts accept a published Activity `snapshot` binding. Snapshot IDs, opaque cursors, frozen cutoffs and 410 recovery guidance keep reads on one version. Activity event detail requires the originating page's snapshot.
+- Added Value maps and label-specific shortlists with frozen percentiles, server-owned signals and explanations, and same-platform peer maps. Map points are returned with `include_map: true`; otherwise `map_points_omitted` reports their count. Ranking pages omit repeated capabilities.
+- Preserved monetary decimal strings, payout bounds, zero/null distinctions, report populations, response definitions, source timestamps and authoritative activity summaries. Payout output schemas include the API's version identity and series fields.
+- Added `opportunity_tiers` to rankings and every per-view alias. The any-of filter supports `elite`, `hot`, `strong`, and `potential`, uses tiers frozen into the Activity version, and is guarded by API capability negotiation.
+- `find_programs` and `find_hunt_targets` combine server-side payout, scope, reward, update, report, response and status predicates with local discovery filters. Pages retain server order; `scan.complete` and `scan.next_cursor` report coverage and continue at the exact next row without mixing versions. Use these tools for combined Activity queries; `search_programs` and `get_opportunities` retain their catalog inputs.
+- Negotiated catalog and Activity filter guards preserve canonical VDP modes and opportunity-kind filtering. Older or disabled APIs cannot silently drop explicit criteria. `find_hunt_targets` rejects unknown inputs, and each Activity tab rejects inputs belonging to another tab.
+- Activity and combined catalog reads share the changes quota and two-request concurrency pool. Private responses are never retained in reusable caches. Activity and chronological failure circuits are isolated from healthy catalog and ranking reads.
+- Reduced discovery overhead with open diagnostic envelope records, while preserving structured results and full-profile tools.
+- Updated `@modelcontextprotocol/sdk` to 1.31.0 and refreshed patched transitive dependencies.
+- Added fixture coverage for every Activity view, discovery response validation, exact identities, cursor and snapshot forwarding, no-store behavior, combined scans, capability guards and concurrency. Package-install smoke checks now exercise Activity and payouts; the deadline regression test accepts scheduling-dependent request counts within the shared budget.
+
 ## 0.2.6 — expanded Pro API
 
 - Added seven direct tools for semantic History, exact program activity, and daily analytics, using one data request per page and lazy change detail.

package/README.md

@@ -135,6 +135,177 @@ 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.
 
+### Activity and payouts
+
+Use `get_activity_capabilities` before choosing a ranking. Its versioned views give
+the enabled metric, period, payout basis, precision, sort and direction together.
+Each ranking requires validated values from at least three platforms before it is
+enabled. User filters do not re-run that gate, so filtering a supported ranking to
+one platform is valid. A 422 means the requested combination is unavailable; never
+silently replace its period or basis.
+
+| Tool | Purpose |
+| --- | --- |
+| `get_activity_capabilities` | Enabled views, directions, label filters and listing readiness |
+| `get_activity_snapshot` | Identity of the current published Activity version; no rows |
+| `get_program_payouts` | One exact program's monetary, received-report and response facts |
+| `get_activity_rankings` | One server-ranked page of any Activity view, selected with `tab` |
+| `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),
+`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:
+`basis`/`precision` for payouts, `category` for updates and all changes,
+`change_type` for status, `launched_within` for reports and response, and
+`report_change_min`/`report_change_max` for reports. Anything else fails before a
+request instead of reaching a different ranking. The `full` profile also keeps
+single-view aliases (`get_activity_payouts`, `get_activity_value`,
+`get_activity_scope`, `get_activity_rewards`, `get_activity_updates`,
+`get_activity_reports`, `get_activity_response`, `get_activity_status` and
+`get_activity_changes`) with the same request path.
+
+Every tab also accepts `opportunity_tiers` (any of `elite`, `hot`, `strong`,
+`potential`): the catalog opportunity tier frozen into the Activity version, so a
+ranking can be narrowed to, for example, Elite and Hot programs.
+`get_activity_capabilities` lists the tiers present in `facets.opportunity_tiers`.
+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
+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
+filtering. Label-specific shortlists use their own criteria, so a small-cohort
+“No payouts seen” program can appear without map percentiles. Keep its received
+count and Tracked/Reported basis together. Explicit unsupported combinations are
+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
+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
+these signals or percentiles over one returned page.
+
+For Activity event detail, supply the event ID and the source page's
+`meta.snapshot_id` as `snapshot`. Keep that snapshot and page size with any detail
+cursor. Legacy `get_history_change_detail` retains its existing History contract.
+
+The ranking tools share `GET /v1/pro/activity/rankings`, fetch one bounded server
+page and return the frozen `meta.as_of`, snapshot ID and opaque `next_cursor`.
+On Activity 410, restart the same ranking without its cursor. For event details,
+refresh the originating Activity page and reuse its new `meta.snapshot_id`.
+Activity ranking tools do not accept `snapshot: "start"` or numeric `after_id`.
+Activity is published in versions about every 30 seconds. `get_activity_snapshot`
+reports the current version; pass its `snapshot_id` as `snapshot` to read
+capabilities, a first page or program payouts from that exact version. Starting a
+read on a version requires at least five minutes of remaining lifetime; an expired
+or withdrawn version returns 410, after which you restart without the binding.
+Never combine rows from different versions. `as_of` is when BBRadar froze its
+calculation, not when a provider paid or updated anything.
+Reuse the same filters, ordering and limit with that cursor. On expiry, restart the
+query; do not merge different snapshots. No browser-like crawling, provider reads
+or client-side global ranking is performed. Reads use the existing shared quota
+and two-request concurrency pool, including per-program payout detail. Private
+results and dynamic capabilities are never retained in reusable response caches.
+
+For example, after confirming the combination is enabled, call
+`get_activity_rankings` with
+`{"tab":"payouts","period":"30d","basis":"tracked","precision":"exact","sort":"paid","direction":"desc","limit":25}`
+for the largest measured increases in the **last 30 days**. The periods are rolling
+windows, not calendar months. Resolve "lately" consistently for high and low payout
+queries: prefer an enabled tracked 30-day comparison, or name a separately ranked
+reported 90-day comparison. An explicit 7- or 30-day request never falls back to a
+90-day or lifetime amount.
+
+With `precision: "proven_bounds"`, descending means **Highest reported minimum**
+using each value's lower bound; ascending means **Lowest reported maximum** using
+its upper bound. Read `sort_directions` because these two orders qualify
+independently. Keep `>`, `<`, interval notation, currency and observation dates in
+the answer. A first baseline is not a payout, a counter increase is not a payment
+date, and a hidden or ambiguous value is not zero.
+
+Reports and resolved counters support `7d`, `30d`, `90d`, `all_time`, and API-only
+`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
+filters must come from current capabilities, and unsupported labels remain errors.
+
+Use exact `platform:handle` identities for `get_program_payouts`; slash-containing
+handles and literal percent signs are preserved. `null`, zero, bounds, report
+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.
+
+`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
+pagination, preserving one global ordering and one stable snapshot. For example, use
+`{"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
+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.
+
+Combined Activity queries require negotiated `activity_filters.enabled=true`.
+Catalog-only program type, canonical VDP mode and `updated` ordering use the
+separately advertised `catalog_filters` contract, so ordinary discovery remains
+available when Activity is disabled. Server-ranked VDP choices are `include`,
+`exclude` and `only`; legacy heuristic `only_likely` / `only_known_no_bounty`
+choices remain in sampled discovery and are never silently mapped to a different
+server predicate. Opportunity kind filters require advertised support and run
+before pagination. Legacy search plus local-only discovery filters remains a
+sampled workflow and is never labelled as a complete server ranking.
+
+The combined inputs cover scope movement, reward changes, active days and change
+counts, report levels and change, resolved counts, response timings, lifecycle
+events, canonical launch cohorts and advertised activity labels. Give each
+period-based signal its own period. `no_increase` and `lower` payout activity use
+tracked 30-day values. All-time report comparisons, unsupported precision or
+coverage states, automatic `recent` cohorts, `resolution_gap`, and
+`opportunity_score` ordering are unavailable in this release; explicit unsupported
+requests fail instead of silently substituting another metric.
+
+With combined inputs alone, `find_programs` reads exactly one server page;
+`max_results` sets its size and `page` continues it. Combined inputs also work
+together with local filters such as `exclude_web3`, `min_wildcards`,
+`min_eligible_targets`, bounty and report-count limits, `competition_risks` and
+`free_submission_only` (no detected submission fee or deposit), plus target samples.
+The MCP then reads full server pages in the server's order and the local filters
+only remove programs, so the result is still a prefix of the global order. It reads
+one page first and prefetches at most two more at a time when the observed match
+rate shows they are needed. `scan.complete` says whether the whole server result
+was examined; otherwise `scan.next_cursor` continues at the exact next row with the
+same filters. A scan never mixes Activity versions: within one call it restarts
+once on the new version, and a cursor from an older version fails with a restart
+instruction.
+
+For example, "a program with recent payouts, low competition, new scope, wide Web2
+scope and no submission fee" is one `find_programs` call:
+`{"payout_period":"30d","payout_positive":true,"scope_period":"30d","scope_added_min":1,"exclude_web3":true,"min_wildcards":1,"competition_risks":["Low"],"free_submission_only":true}`.
+`find_hunt_targets` accepts the same Activity inputs (with `surface_mode: "web2"`
+and `free_submission_only`) and returns ranked finalists with exact target samples.
+Activity-filtered catalog reads count toward the API's shared changes quota, so the
+MCP routes them through the same two-request concurrency pool as rankings and
+change feeds.
+
+It accepts at most one opportunity tier, and sampled sorts such as
+`best_hunt_value` stay in legacy discovery, which still works when no combined
+inputs are supplied. Do not form combined results by intersecting separately
+paginated tools. VDP mode is applied on the server for combined queries,
+preserving unknown reward types under `exclude`.
+
 ### Pro History and analytics
 
 The `2026-09-24` API contract maps to these direct MCP tools. Each call reads one page unless the caller explicitly supplies a cursor for the next page. Change detail is fetched only when requested.
@@ -179,7 +350,7 @@ For cacheable responses, large target and change collections return at most 50 i
 
 ## Performance Tuning
 
-The defaults expose the 25-tool core surface and compact text results while enabling bounded concurrency, in-flight request coalescing, endpoint circuit breakers, and response caching only when upstream cache policy permits it. The Pro deployment currently sends `private, no-store`, so its responses are not placed in the reusable response cache or stale-while-revalidate cache. Set the tool profile to `full` when all specialized tools are needed.
+The defaults expose the 30-tool core surface and compact text results while enabling bounded concurrency, in-flight request coalescing, endpoint circuit breakers, and response caching only when upstream cache policy permits it. The Pro deployment currently sends `private, no-store`, so its responses are not placed in the reusable response cache or stale-while-revalidate cache. Set the tool profile to `full` when all specialized tools are needed.
 
 | Environment variable | Default | Purpose |
 | --- | ---: | --- |
@@ -189,7 +360,7 @@ The defaults expose the 25-tool core surface and compact text results while enab
 | `BBRADAR_MCP_MAX_CONCURRENT_REQUESTS` | `6` | Maximum simultaneous upstream BBRadar API requests. |
 | `BBRADAR_MCP_REQUEST_TIMEOUT_SECONDS` | `30` | Total upstream request deadline, including queue time. |
 | `BBRADAR_MCP_COMPACT_TOOL_TEXT` | `true` | Avoid duplicating full results for clients that consume MCP `structuredContent`. Set to `false` for legacy text-only clients. |
-| `BBRADAR_MCP_TOOL_PROFILE` | `core` | Compact 25-tool discovery surface. Set to `full` for every specialized tool. |
+| `BBRADAR_MCP_TOOL_PROFILE` | `core` | Compact 30-tool discovery surface. Set to `full` for every specialized tool. |
 | `BBRADAR_MCP_PROGRAM_STALE_WHILE_REVALIDATE_SECONDS` | `300` | Maximum stale window for exact program metadata while one background refresh runs. |
 | `BBRADAR_MCP_CIRCUIT_BREAKER_FAILURE_THRESHOLD` | `3` | Consecutive retryable endpoint failures before its circuit opens. |
 | `BBRADAR_MCP_CIRCUIT_BREAKER_COOLDOWN_SECONDS` | `30` | Endpoint circuit cooldown before a new request is admitted. |
@@ -220,7 +391,7 @@ Persisted numeric feed checkpoints are scoped to the API destination and credent
 
 Use `find_hunt_targets` as the default one-call path when a request combines good rewards, wide scope, Web2/Web3 constraints, competition, target quality, or recently added targets. It performs one catalog pass, fetches the bounded recent-additions feed in parallel, enriches only the finalists with exact in-scope bounty-eligible target samples, and returns a final compact ranking. Its result explicitly requires no follow-up calls; use `get_program_targets` only when the user asks for an exhaustive scope dump for one selected program.
 
-`find_hunt_targets` supports arbitrary platform inclusion/exclusion, scope/target/language filters, reward and breadth thresholds, Web2/Web3 modes, target-intelligence filters, freshness windows, and balanced/reward/scope/freshness/competition ranking. It suppresses bulk `bbradar://` resource links while preserving each program's public BBRadar and platform URLs, preventing large shortlists from flooding model context.
+`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.
 
 ```json
 {
@@ -269,6 +440,20 @@ This path uses one recent-changes request. Use `find_wildcard_programs` for a ra
 - `get_history_change_detail`
 - `get_program_history`
 - `get_program_activity`
+- `get_activity_capabilities`
+- `get_activity_snapshot`
+- `get_activity_rankings`
+- `get_program_payouts`
+- `get_activity_payouts`
+- `get_activity_value`
+- `get_activity_scope`
+- `get_activity_rewards`
+- `get_activity_updates`
+- `get_activity_reports`
+- `get_activity_response`
+- `get_activity_status`
+- `get_activity_changes`
+- `get_activity_change_detail`
 - `get_analytics_platform_series`
 - `get_analytics_program_activity`
 - `get_analytics_program_detail`

package/benchmark/pro-benchmark.mjs

@@ -12,14 +12,29 @@ const responses = {
   "/pro/activity/programs/HackerOne:bench": { program_id: "HackerOne:bench", activity_summary: { additions: 0, last_observed_at: null } },
   "/pro/analytics/programs/activity": { programs: historyRows.map((row) => ({ id: row.program.id, activity_days: 1 })), meta: { generation: 3, provisional: false, unsupported_metrics: ["repository_changes"] } }
 };
+// Activity catalog: every fifth program passes the Web2, wildcard, competition
+// and fee filters of the combined benchmark question.
+const catalog = Array.from({ length: 250 }, (_, i) => ({ id: `HackerOne:p${i}`, platform: "HackerOne", handle: `p${i}`, name: `Program ${i}`, program_type: "paid", is_active: true,
+  bounty_min: 100, bounty_max: 5000, report_count: 10, competition_risk: i % 5 === 3 ? "High" : "Low",
+  scope_tags: i % 5 === 1 ? ["smart-contract"] : ["domain", "api", "wildcard"], submission_cost: i % 5 === 2 ? { amount: 25, maximum_amount: 25 } : null,
+  target_counts: { total: 30, in_scope: 30, eligible_for_bounty: 30, wildcard: i % 5 === 4 ? 0 : 3 }, payout_summary: { "30d": { amount: "1500", currency: "USD" } } }));
+const catalogEndpoint = { enabled: true, max_page_size: 100, activity_filters: { enabled: true }, catalog_filters: { enabled: true } };
+function catalogPage(url) {
+  const page = Number(url.searchParams.get("page") ?? 1), size = Number(url.searchParams.get("page_size") ?? 50);
+  return { programs: catalog.slice((page - 1) * size, page * size), meta: { page, page_size: size, total: catalog.length, total_pages: Math.ceil(catalog.length / size), activity_snapshot_id: "a".repeat(64) } };
+}
 const api = http.createServer(async (req, res) => {
-  const path = new URL(req.url, "http://fixture").pathname.replace(/^\/api\/v1/, "");
+  const url = new URL(req.url, "http://fixture");
+  const path = url.pathname.replace(/^\/api\/v1/, "");
   counters.requests += 1;
   counters.active += 1;
   counters.peak = Math.max(counters.peak, counters.active);
   await new Promise((resolve) => setTimeout(resolve, 5));
   const payload = path === "/pro/capabilities"
-    ? { contract_version: "2026-09-24", endpoints: Object.fromEntries(["history_changes", "history_change_detail", "program_activity", "analytics_program_activity"].map((key) => [key, { enabled: true, history_capture_enabled: true }])) }
+    ? { contract_version: "2026-10-06", endpoints: { ...Object.fromEntries(["history_changes", "history_change_detail", "program_activity", "analytics_program_activity", "activity_rankings"].map((key) => [key, { enabled: true, history_capture_enabled: true }])), programs: catalogEndpoint, opportunities: catalogEndpoint, program_targets: { max_page_size: 500 } } }
+    : path === "/pro/programs" ? catalogPage(url)
+    : /^\/pro\/programs\/.+\/targets$/.test(path) ? { targets: [{ identifier: "api.example.test", target_type: "domain", in_scope: true, eligible_for_bounty: true }], meta: { total: 1, total_pages: 1 } }
+    : path === "/pro/activity/rankings" ? { tab: "payouts", period: "30d", sort: "paid", direction: "desc", rows: catalog.slice(0, 10).map((program) => ({ program, paid: program.payout_summary["30d"] })), capabilities: { tabs: [{ id: "payouts", views: [] }], facets: { tags: Array.from({ length: 300 }, (_, i) => `tag-${i}`) } }, meta: { total: 250, has_more: true, next_cursor: "next", snapshot_id: "a".repeat(64) } }
     : path.startsWith("/pro/history/changes/")
       ? { change: historyRows[0], items: [{ before: null, after: { count: 0 } }], meta: { has_more: false } }
       : responses[path] ?? { detail: "missing" };
@@ -75,10 +90,17 @@ try {
   const detail = await measure("get_history_change_detail", { change_id: "c0", limit: 1 });
   const activity = await measure("get_program_activity", { program_id: "HackerOne:bench" });
   const analytics = await measure("get_analytics_program_activity", { limit: 10 });
+  const activityRanking = await measure("get_activity_rankings", { tab: "payouts", period: "30d", limit: 10 });
+  // "Recent payouts, low competition, new scope, wide Web2 scope, no submission fee" in one call.
+  const question = { payout_period: "30d", payout_positive: true, scope_period: "30d", scope_added_min: 1, exclude_web3: true, min_wildcards: 1, competition_risks: ["Low"], free_submission_only: true };
+  const combinedQuestion = await measure("find_programs", { ...question, max_results: 10 });
+  const combinedHunt = await measure("find_hunt_targets", { payout_period: "30d", payout_positive: true, scope_period: "30d", scope_added_min: 1, surface_mode: "web2", min_wildcards: 1, free_submission_only: true, include_recent_changes: false, max_results: 5 });
   reset();
   const heapBefore = process.memoryUsage().heapUsed;
   const parallel = await Promise.all(Array.from({ length: 10 }, (_, i) => client.callTool({ name: "get_history_changes", arguments: { search: `bench${i}`, limit: 1 } })));
   const concurrency = { calls: parallel.length, upstream_requests: counters.requests, peak_upstream_requests: counters.peak, heap_delta_bytes: process.memoryUsage().heapUsed - heapBefore };
-  if ([history, detail, activity, analytics].some((entry) => entry.upstream_requests !== 20) || concurrency.peak_upstream_requests > 2 || concurrency.upstream_requests !== 10) throw new Error("Pro request-count or shared-concurrency regression");
-  process.stdout.write(JSON.stringify({ fixture: true, simulated_upstream_delay_ms: 5, direct_history: directHistory, estimated_mcp_overhead_p50_ms: Math.round((history.p50_ms - directHistory.p50_ms) * 100) / 100, history_lazy_detail: { eager_baseline_requests: 11, feed_only_requests: 1, requested_detail_requests: 2 }, tools: { history, detail, activity, analytics }, concurrency }, null, 2) + "\n");
+  if ([history, detail, activity, analytics, activityRanking, combinedQuestion].some((entry) => entry.upstream_requests !== 20) || concurrency.peak_upstream_requests > 2 || concurrency.upstream_requests !== 10) throw new Error("Pro request-count or shared-concurrency regression");
+  // The candidate pool's catalog pages plus one exact target sample per finalist.
+  if (combinedHunt.upstream_requests > 20 * (3 + 5)) throw new Error(`Activity hunt request-count regression: ${combinedHunt.upstream_requests}`);
+  process.stdout.write(JSON.stringify({ fixture: true, simulated_upstream_delay_ms: 5, direct_history: directHistory, estimated_mcp_overhead_p50_ms: Math.round((history.p50_ms - directHistory.p50_ms) * 100) / 100, history_lazy_detail: { eager_baseline_requests: 11, feed_only_requests: 1, requested_detail_requests: 2 }, tools: { history, detail, activity, analytics, activity_ranking: activityRanking, combined_question: combinedQuestion, combined_hunt: combinedHunt }, concurrency }, null, 2) + "\n");
 } finally { await client.close(); await server.close(); api.close(); }

package/dist/activityContract.d.ts

@@ -0,0 +1,2 @@
+/** Catalog metadata stays available when Activity computation is disabled. */
+export declare function requiresActivityQuery(input?: Record<string, unknown>): boolean;

package/dist/activityContract.js

@@ -0,0 +1,15 @@
+const ACTIVITY_FILTERS = new Set([
+    "payout_metric", "payout_period", "payout_currency", "payout_precision", "payout_min", "payout_max",
+    "payout_positive", "payout_activity", "scope_period", "scope_added_min", "scope_removed_min",
+    "scope_net_min", "scope_net_max", "reward_period", "reward_change", "reward_change_min_pct",
+    "updates_period", "active_days_min", "changes_min", "change_category", "reports_period",
+    "reports_min", "reports_max", "reports_change", "reports_change_min_pct", "launched_within",
+    "resolved_period", "resolved_min", "last_resolved_within", "first_response_max_hours",
+    "time_to_bounty_max_hours", "status_period", "status_change", "current_status", "activity_labels",
+]);
+/** Catalog metadata stays available when Activity computation is disabled. */
+export function requiresActivityQuery(input = {}) {
+    return Object.entries(input).some(([key, value]) => value !== undefined && value !== null
+        && (key === "sort_by" ? value !== "updated" : ACTIVITY_FILTERS.has(key)));
+}
+//# sourceMappingURL=activityContract.js.map

package/dist/activityContract.js.map

@@ -0,0 +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"}

package/dist/bbradarClient.d.ts

@@ -203,6 +203,11 @@ export declare class BBRadarClient {
     getHistoryChangeDetail(changeId: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
     getProgramHistory(programId: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
     getProgramActivity(programId: string): Promise<ApiResult<unknown>>;
+    getActivityCapabilities(query?: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getActivitySnapshot(): Promise<ApiResult<unknown>>;
+    getActivityRankings(query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getActivityChangeDetail(eventId: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getProgramPayouts(programId: string, query?: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
     getAnalyticsPlatformSeries(platform: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
     getAnalyticsProgramActivity(query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
     getAnalyticsProgramDetail(programId: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;

package/dist/bbradarClient.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { requiresActivityQuery } from "./activityContract.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { TtlCache } from "./cache.js";
 import { stableStringify } from "./json.js";
@@ -356,7 +357,8 @@ export class BBRadarClient {
     getOpportunities(level, query) {
         return this.request({
             path: `/pro/opportunities/${encodeURIComponent(level)}`,
-            query
+            query,
+            ...snapshotAwareReadControls(query, {}, true, this.config.requestTimeoutMs)
         });
     }
     getHistoryChanges(query) {
@@ -371,6 +373,21 @@ export class BBRadarClient {
     getProgramActivity(programId) {
         return this.request({ path: `/pro/activity/programs/${encodeProgramIdPath(programId)}`, cache: false });
     }
+    getActivityCapabilities(query = {}) {
+        return this.request({ path: "/pro/activity/capabilities", query, cache: false });
+    }
+    getActivitySnapshot() {
+        return this.request({ path: "/pro/activity/snapshot", cache: false });
+    }
+    getActivityRankings(query) {
+        return this.request({ path: "/pro/activity/rankings", query, cache: false });
+    }
+    getActivityChangeDetail(eventId, query) {
+        return this.request({ path: `/pro/activity/events/${encodeURIComponent(eventId)}`, query, cache: false });
+    }
+    getProgramPayouts(programId, query = {}) {
+        return this.request({ path: `/pro/payouts/programs/${encodeProgramIdPath(programId)}`, query, cache: false });
+    }
     getAnalyticsPlatformSeries(platform, query) {
         return this.request({ path: `/pro/analytics/platforms/${encodeURIComponent(platform)}/series`, query, cache: false });
     }
@@ -524,11 +541,12 @@ export class BBRadarClient {
                 });
             }
         }
-        return this.withRequestSlot(options.path, async () => {
-            const rateLimitBucket = rateLimitEndpointGroup(options.path);
+        return this.withRequestSlot(options.path, options.query, async () => {
+            const rateLimitBucket = rateLimitEndpointGroup(options.path, options.query);
+            const circuitBucket = activityCircuitBucket(options.path, options.query) ?? rateLimitBucket;
             if (options.signal?.aborted)
                 throw new BBRadarApiError({ message: "BBRadar API request was cancelled.", requestId, status: 408 });
-            this.assertCircuitClosed(requestId, rateLimitBucket);
+            this.assertCircuitClosed(requestId, circuitBucket);
             this.reserveUpstreamRequest(requestId, rateLimitBucket);
             const startedAt = Date.now();
             const controller = new AbortController();
@@ -554,7 +572,7 @@ export class BBRadarClient {
                 const response = await fetch(url, init);
                 status = response.status;
                 const noStore = /(?:^|,)\s*(?:no-store|no-cache|private)\b/i.test(response.headers.get("cache-control") ?? "");
-                this.observeCircuitResponse(rateLimitBucket, response.status);
+                this.observeCircuitResponse(circuitBucket, response.status);
                 this.observeUpstreamRateLimit(rateLimitBucket, response.headers, response.status);
                 const upstreamRequestId = extractRequestId(response.headers);
                 const data = await parseResponseBody(response);
@@ -593,10 +611,10 @@ export class BBRadarClient {
                 if (options.signal?.aborted) {
                     const timedOut = options.signal.reason instanceof Error && options.signal.reason.name === "TimeoutError";
                     if (timedOut)
-                        this.observeCircuitFailure(rateLimitBucket);
+                        this.observeCircuitFailure(circuitBucket);
                     throw new BBRadarApiError({ message: timedOut ? "BBRadar API tool deadline exceeded." : "BBRadar API request was cancelled.", requestId, status: 408 });
                 }
-                this.observeCircuitFailure(rateLimitBucket);
+                this.observeCircuitFailure(circuitBucket);
                 throw new BBRadarApiError({
                     message: error instanceof Error && error.name === "AbortError" ? "BBRadar API request timed out." : "BBRadar API request failed.",
                     requestId,
@@ -633,8 +651,8 @@ export class BBRadarClient {
             }
         });
     }
-    async withRequestSlot(path, callback, deadline, requestId, signal) {
-        const endpointGroup = concurrencyEndpointGroup(path);
+    async withRequestSlot(path, query, callback, deadline, requestId, signal) {
+        const endpointGroup = concurrencyEndpointGroup(path, query);
         if (endpointGroup === undefined) {
             return this.withGlobalRequestSlot(callback, deadline, requestId, signal);
         }
@@ -1073,6 +1091,10 @@ function metricEndpoint(path) {
         return "/pro/history/programs/:program_id";
     if (/^\/pro\/activity\/programs\/.+/.test(path))
         return "/pro/activity/programs/:program_id";
+    if (/^\/pro\/activity\/events\/.+/.test(path))
+        return "/pro/activity/events/:event_id";
+    if (/^\/pro\/payouts\/programs\/.+/.test(path))
+        return "/pro/payouts/programs/:program_id";
     if (/^\/pro\/analytics\/platforms\/.+\/series$/.test(path))
         return "/pro/analytics/platforms/:platform/series";
     if (/^\/pro\/analytics\/programs\/.+/.test(path) && path !== "/pro/analytics/programs/activity")
@@ -1088,8 +1110,26 @@ function metricEndpoint(path) {
     }
     return path;
 }
-function rateLimitEndpointGroup(path) {
-    if (path === "/pro/targets/changes" || /^\/pro\/(?:history|activity|analytics)\//.test(path)) {
+// The API admits Activity-filtered catalog reads in its heavy "changes" group,
+// sharing that quota and in-flight limit with the change feeds.
+function isActivityCatalogRead(path, query = {}) {
+    return (path === "/pro/programs" || path.startsWith("/pro/opportunities/")) && requiresActivityQuery(query);
+}
+function activityCircuitBucket(path, query = {}) {
+    const activityCatalog = isActivityCatalogRead(path, query);
+    // Chronological feeds can exceed their own projection budget while complete
+    // rankings remain healthy. Keep this a finite group, never a caller-keyed map.
+    if ((path === "/pro/activity/rankings" && (query.tab === "status" || query.tab === "all_changes"))
+        || path.startsWith("/pro/activity/events/")
+        || (activityCatalog && query.status_change !== undefined && query.status_change !== null)) {
+        return "activity_chronological";
+    }
+    if (/^\/pro\/(?:activity|payouts)\//.test(path))
+        return "activity_reads";
+    return activityCatalog ? "activity_catalog" : undefined;
+}
+function rateLimitEndpointGroup(path, query) {
+    if (path === "/pro/targets/changes" || /^\/pro\/(?:history|activity|analytics|payouts)\//.test(path) || isActivityCatalogRead(path, query)) {
         return "change_feeds";
     }
     if (path === "/pro/repositories/changes") {
@@ -1112,8 +1152,9 @@ function rateLimitEndpointGroup(path) {
     }
     return "other";
 }
-function concurrencyEndpointGroup(path) {
-    if (path === "/pro/targets/changes" || path === "/pro/repositories/changes" || /^\/pro\/(?:history|activity|analytics)\//.test(path)) {
+function concurrencyEndpointGroup(path, query) {
+    if (path === "/pro/targets/changes" || path === "/pro/repositories/changes" || /^\/pro\/(?:history|activity|analytics|payouts)\//.test(path)
+        || isActivityCatalogRead(path, query)) {
         return "change_feeds";
     }
     if (path === "/pro/targets/export") {