@bbradar/mcp 0.2.6 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Release notes
 
+## 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.
+- 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,179 @@ 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
+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.
@@ -173,13 +346,29 @@ 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.
 
 ## 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 +378,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. |
@@ -208,6 +397,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.
@@ -220,7 +427,13 @@ 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.
+
+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
 {
@@ -269,6 +482,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/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));
+}