@bbradar/mcp 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# 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.
+- Added `program_kind` filtering and source-classified contest discovery. Program projections now retain schedule precision, lifecycle state, fee metadata, Self-Hosted verification, and archive/catalog identity.
+- Preserved the distinct pagination models: numeric target/repository bookmarks, stable snapshot tokens, and five-minute opaque History/analytics cursors. Snapshot continuation now advances pages without mixing tokens.
+- Routed new reads through the existing shared changes quota and two-request concurrency pool. Added a 100-request queue ceiling and a total request deadline that includes queue time.
+- Connected MCP cancellation and a total tool deadline to HTTP requests, including compatibility with Node 20.0.0. Cancelling one caller preserves an in-flight request needed by another caller; unused work is aborted without opening the circuit breaker.
+- Preserved explicit unknown fee, report-count, and scoring values in compact results, and kept case-sensitive program IDs distinct in fallback caches.
+- Scoped persisted numeric feed checkpoints to the API destination and credential. Existing 0.2.5 persisted streams need one explicit `after_id` seed after upgrading.
+- Honored upstream `private` and `no-store` on success and error caches, including stale refreshes. Private results are not kept in local continuation or export resources.
+- Added deterministic route, schema, privacy, package-installation, and benchmark coverage.

package/README.md

@@ -1,6 +1,6 @@
 # @bbradar/mcp
 
-Local STDIO MCP server for [bbradar.io](https://bbradar.io) Pro subscribers. It lets MCP clients query [bbradar.io](https://bbradar.io) platform and Self-Hosted program profiles, active targets, target-level opportunity intelligence, recent target changes, and repository-change events through a local npm package.
+Local STDIO MCP server for [bbradar.io](https://bbradar.io) Pro subscribers. It exposes program and target discovery, semantic History, exact activity, daily analytics, and repository-change events through a local npm package.
 
 ## Requirements
 
@@ -115,6 +115,7 @@ Most tools that accept `program_id` also accept a human program name or handle.
 Self-Hosted programs use IDs such as `Self-Hosted:program-slug`. They are available through program search, exact program detail, reverse target search, program-target tools, and the normal `find_hunt_targets` ranking path. Their `data_capabilities` field identifies unavailable source signals; the MCP server does not invent opportunity scores, public report counts, target-change history, submission costs, repository changes, or numeric competition evidence for that catalog. A Self-Hosted-only hunt skips the unsupported target-change feed and derives recent-target evidence from current inventory timestamps. A Self-Hosted-only repository hunt returns immediately with guidance instead of spending upstream requests on an unsupported feed; mixed repository hunts omit Self-Hosted and continue with supported platforms.
 
 `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.
 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.
@@ -122,7 +123,7 @@ The full tool profile also exposes `search_targets`, a one-request low-level wra
 `find_programs_by_target` defaults to flexible target matching. It accepts bare domains, full URLs, wildcard scopes, target names, package/repo-style identifiers, or short phrases like `known api target`.
 It uses the Pro API's direct reverse-target-search route first, including for Self-Hosted targets, and only falls back to sampled target lists when an older API deployment does not expose that route.
 
-`export_targets` uses the bounded bearer `POST /api/v1/pro/targets/export` route directly. JSON exports preserve `program_id` on every target; CSV previews are capped in the tool result while the complete payload remains available for ten minutes through the returned `bbradar://exports` resource. The local resource store is capped at 25 entries and 64 MiB in aggregate, and CSV formula/control-byte neutralization is applied independently of the API.
+`export_targets` uses the bounded bearer `POST /api/v1/pro/targets/export` route directly. JSON exports preserve `program_id` on every target. When the API marks a response private or `no-store`, the complete sanitized export is returned only in the current structured tool result; it is not saved to a reusable resource. For responses that permit storage, the complete payload remains available for ten minutes through `bbradar://exports`. The local resource store is capped at 25 entries and 64 MiB in aggregate, and CSV formula/control-byte neutralization is applied independently of the API.
 
 `get_program_targets` forwards text, target type, eligibility, minimum Target Opportunity Score, Target Opportunity Label, and competition-risk filters to the API. Compact output retains the score, label, competition risk, and Why This Target; full output also includes the score breakdown and reason fields.
 When no local scope filtering is needed, offsets begin at the corresponding upstream
@@ -134,6 +135,199 @@ 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.
+
+| Pro API route | MCP tool | Page default |
+| --- | --- | ---: |
+| `GET /v1/pro/history/changes` | `get_history_changes` | 50 |
+| `GET /v1/pro/history/changes/{change_id}` | `get_history_change_detail` | 50 |
+| `GET /v1/pro/history/programs/{program_id}` | `get_program_history` | 50 |
+| `GET /v1/pro/activity/programs/{program_id}` | `get_program_activity` | one summary |
+| `GET /v1/pro/analytics/platforms/{platform}/series` | `get_analytics_platform_series` | 100 days |
+| `GET /v1/pro/analytics/programs/activity` | `get_analytics_program_activity` | 50 programs |
+| `GET /v1/pro/analytics/programs/{program_id}` | `get_analytics_program_detail` | 100 days |
+
+History defaults to 90 days; `days: 0` requests all retained History for an exact program. Use the scoped `get_program_history` route for `Self-Hosted:slug` IDs. A History response contains `coverage`, `tracking_since`, `observed_at`, `published_at`, and `provider_revision`; an empty `changes` array with `capture_enabled: false` means unavailable capture rather than a confirmed absence of changes. `catalog_id` identifies a Self-Hosted catalog record for later catalog reads, while `id` preserves the archive identity. Program IDs with slashes, literal percent signs, and case distinctions are preserved.
+
+Analytics dates are inclusive UTC `YYYY-MM-DD`. Omit both dates for the API's latest 90-day interval. The daily retention window is 36 calendar months. The category ranking supports `all`, `scope`, `rewards`, `rules`, `schedule`, `costs`, and `lifecycle`; repository metrics remain unsupported. Inspect `model_version`, `generation`, `projection_pending`, `provisional`, `unsupported_metrics`, and observation coverage. A carried inventory state is not a fresh source verification, and `null` is not measured zero. Use `get_analytics_program_activity` for server-side activity ranking; the program-list API has no activity sort. Other client-side rankings remain bounded samples, not complete catalog sorts.
+
+For example, call `get_program_history` with `{ "program_id": "Self-Hosted:program-slug", "days": 90, "limit": 50 }`, then pass `meta.next_cursor` back with the same arguments for the next page. Call `get_history_change_detail` with a returned change ID only when before/after items are needed. `get_program_activity` reads the exact `activity_summary`; `summarize_program_activity` keeps its target-change samples explicitly separate from semantic History.
+
+History and analytics cursors are signed, opaque, and expire after five minutes. Reuse them with the same filters and page size; never persist them as numeric feed checkpoints. On 410, restart an expired History or analytics query, start a new snapshot for an expired snapshot token, reconcile inventory for a retained numeric-feed gap, or choose supported analytics dates when outside retention. Do not combine pages from different snapshots or analytics generations. The target-change feed describes latest retained state and is not a complete immutable event journal.
+
 If a cursor predates retained API history, the MCP refreshes the relevant current
 target or repository-change inventory within the same page/time bounds. It advances to a new
 baseline only after the bounded inventory completes and unchanged feed probes prove
@@ -152,11 +346,11 @@ inventory ends. Missing public scope is treated as out of scope.
 
 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.
 
-Large target and change collections return at most 50 inline records by default. The remainder is held in a bounded, ten-minute in-memory continuation and exposed through a `bbradar://continuations` resource link. This keeps model context small without losing access to the complete bounded result.
+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 18-tool core surface and compact text results while enabling bounded concurrency, positive response caching, in-flight request coalescing, stale-while-revalidate program metadata, endpoint circuit breakers, and short negative caching for repeated 404/405 lookups. 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 |
 | --- | ---: | --- |
@@ -164,9 +358,9 @@ The defaults expose the 18-tool core surface and compact text results while enab
 | `BBRADAR_MCP_NEGATIVE_CACHE_TTL_SECONDS` | `15` | Repeated 404/405 cache lifetime. Set to `0` to disable. |
 | `BBRADAR_MCP_CACHE_MAX_ENTRIES` | `500` | Maximum entries in each local response cache. |
 | `BBRADAR_MCP_MAX_CONCURRENT_REQUESTS` | `6` | Maximum simultaneous upstream BBRadar API requests. |
-| `BBRADAR_MCP_REQUEST_TIMEOUT_SECONDS` | `30` | Timeout for each active upstream request; queue time is excluded. |
+| `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 18-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. |
@@ -175,21 +369,29 @@ The defaults expose the 18-tool core surface and compact text results while enab
 | `BBRADAR_MCP_CONTINUATION_TTL_SECONDS` | `600` | Lifetime of in-memory continuation results. |
 | `BBRADAR_MCP_ALLOW_INSECURE_HTTP` | `false` | Explicitly allow an HTTP API base URL outside loopback for a trusted private development network. Never enable for internet traffic. |
 
-No performance variables are required. Capability-derived page limits and snapshot support, caching, request coalescing, server-side name resolution, reverse-target search, early stopping, bounded concurrency, aggregate-call parallelism, a 64 KiB request-body ceiling, a 16 MiB upstream response ceiling, automatic HTTP compression handling, connection reuse, and upstream quota protection are always active. Unsupported capability-gated tools are removed from discovery. Target responses expose upstream pagination state so an AI client does not mistake a capped page for a complete inventory.
+No performance variables are required. Capability-derived page limits and snapshot support, cache-policy-aware caching, request coalescing, server-side name resolution, reverse-target search, early stopping, bounded concurrency and queues, aggregate-call parallelism, a 64 KiB request-body ceiling, a 16 MiB upstream response ceiling, automatic HTTP compression handling, connection reuse, and upstream quota protection are always active. Target responses expose upstream pagination state so an AI client does not mistake a capped page for a complete inventory.
 
-The client learns the API's `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers per endpoint group. Once an observed group reaches zero, it blocks additional requests to that group locally until reset instead of repeatedly hitting the API, while unrelated endpoint groups remain usable. Target and repository changes share one quota state and one conservative two-request concurrency pool. A rolling 60-second guard also enforces the documented shared key-and-IP ceiling across uncached upstream requests. Real `423`, `429`, and `503` responses honor `Retry-After` as a local cooldown, capped at ten minutes so a malformed upstream header cannot lock the MCP process indefinitely. Requests are not automatically retried, so one MCP action cannot amplify an admission or rate-limit response into more API calls. The global upstream concurrency default is six and bulk exports are capped at two; cursor page walking is strictly sequential.
+The client learns the API's `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers per endpoint group. Once an observed group reaches zero, it blocks additional requests to that group locally until reset instead of repeatedly hitting the API, while unrelated endpoint groups remain usable. Target changes, repository changes, History, exact activity, and analytics share one quota state and one conservative two-request concurrency pool. A rolling 60-second guard also enforces the documented shared key-and-IP ceiling across uncached upstream requests. Real `423`, `429`, and `503` responses honor `Retry-After` as a local cooldown, capped at ten minutes so a malformed upstream header cannot lock the MCP process indefinitely. Requests are not automatically retried. The global upstream concurrency default is six, each queue is capped at 100, and bulk exports are capped at two.
 
 The bearer API destination must use HTTPS. Loopback HTTP remains available for local development; non-loopback HTTP requires the explicit `BBRADAR_MCP_ALLOW_INSECURE_HTTP=true` opt-in. API base URLs containing embedded credentials, query strings, fragments, or non-HTTP schemes are rejected before the key can be sent.
 
 Call `get_mcp_status` to inspect cache and stale-hit rates, circuit states, cursor persistence, concurrency, negotiated capabilities, upstream quotas, actual request counts, per-endpoint status totals, and timing.
 
-Run `npm run benchmark` for the deterministic local performance benchmark. It reports request and byte reductions for reverse target discovery, exact-program cache efficiency, and context reduction from bounded continuations.
+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.
+
+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.
+
+MCP cancellation reaches active and queued HTTP work. Each tool shares one total deadline across its requests, using `BBRADAR_MCP_REQUEST_TIMEOUT_SECONDS`; snapshot creation keeps its 60-second minimum. Identical concurrent GETs can share one upstream request, and cancelling one caller preserves it while another caller still needs it.
+
+Persisted numeric feed checkpoints are scoped to the API destination and credential. When upgrading from 0.2.5, seed each persisted stream once with `after_id` before using `resume_cursor`; old unscoped checkpoints are not reused.
 
 ### Flexible multi-signal discovery
 
 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
 {
@@ -234,6 +436,27 @@ This path uses one recent-changes request. Use `find_wildcard_programs` for a ra
 - `get_program_targets`
 - `get_recent_changes`
 - `get_repository_changes`
+- `get_history_changes`
+- `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`
 - `find_hunt_targets`
 - `find_repository_hunt_targets`
 - `get_opportunities`

package/benchmark/compare-revisions.mjs

@@ -0,0 +1,164 @@
+// Maintainer check: npm run build && node --expose-gc benchmark/compare-revisions.mjs [git-ref]
+// Compiles a read-only source snapshot in a temporary directory; leaves the checkout untouched.
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import ts from "typescript";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { BBRadarClient } from "../dist/bbradarClient.js";
+import { createBbradarServer } from "../dist/server.js";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const ref = process.argv[2] ?? "HEAD";
+const baselineCommit = execFileSync("git", ["rev-parse", "--verify", `${ref}^{commit}`], { cwd: root, encoding: "utf8" }).trim();
+const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "bbradar-compare-"));
+const counts = { requests: 0, bytes: 0, active: 0, peak: 0 };
+const now = new Date().toISOString();
+const programs = Array.from({ length: 100 }, (_, i) => ({
+  id: `Platform:program-${i}`, handle: `program-${i}`, name: `Program ${i}`, platform: "Platform",
+  program_kind: "bounty", is_active: true, scope_tags: ["domain", "api", "wildcard"],
+  added_at: now, last_updated: now, bounty_min: 100, bounty_max: 5000 + i * 100, report_count: i,
+  target_counts: { total: 20, in_scope: 20, eligible_for_bounty: 20, wildcard: 2 },
+  target_activity: { latest_change_at: now, added_24h: 1, added_7d: 2 }
+}));
+const targets = Array.from({ length: 20 }, (_, i) => ({
+  identifier: `api-${i}.example`, target_type: "domain", in_scope: true, eligible_for_bounty: true,
+  wildcard: i < 2, targetOpportunityScore: 75, targetOpportunityLabel: "Strong Target", competitionRisk: "Low",
+  scoreVersion: 3, evidenceCoverage: { source: "verified" }, targetScoreBreakdown: { scope: 30, freshness: 20 }
+}));
+let cacheControl = "private, no-store";
+const api = http.createServer(async (req, res) => {
+  counts.requests += 1;
+  counts.active += 1;
+  counts.peak = Math.max(counts.peak, counts.active);
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  const url = new URL(req.url, "http://fixture");
+  const endpoint = url.pathname.replace(/^\/api\/v1/, "");
+  let payload;
+  if (endpoint === "/pro/programs") payload = { programs: programs.slice(0, Number(url.searchParams.get("page_size") ?? 100)), meta: { total_pages: 1 } };
+  else if (endpoint.endsWith("/targets")) payload = { targets, meta: { total: 20, total_pages: 1 } };
+  else if (endpoint.startsWith("/pro/programs/")) payload = programs[0];
+  else if (endpoint === "/pro/targets/search") payload = { results: [{ program: programs[0], target: targets[0] }], meta: { has_more: false } };
+  else if (endpoint === "/pro/targets/changes") payload = { results: programs.slice(0, 10).map((program, i) => ({ id: i + 1, program, target: targets[i], change_type: "added", changed_at: now })), meta: { total_pages: 1, has_more: false } };
+  else { res.statusCode = 404; payload = { detail: "missing fixture route" }; }
+  const body = JSON.stringify(payload);
+  counts.bytes += Buffer.byteLength(body);
+  res.setHeader("content-type", "application/json");
+  res.setHeader("cache-control", cacheControl);
+  res.end(body);
+  counts.active -= 1;
+});
+const sessions = [];
+const reset = () => { counts.requests = 0; counts.bytes = 0; counts.peak = 0; };
+const round = (n) => Math.round(n * 100) / 100;
+function percentile(values, p) { return [...values].sort((a, b) => a - b)[Math.ceil(values.length * p) - 1]; }
+
+try {
+  fs.writeFileSync(path.join(temporary, "package.json"), '{"type":"module"}');
+  fs.symlinkSync(path.join(root, "node_modules"), path.join(temporary, "node_modules"), "junction");
+  const sources = execFileSync("git", ["ls-tree", "-r", "--name-only", baselineCommit, "src"], { cwd: root, encoding: "utf8" }).trim().split(/\r?\n/).filter((name) => name.endsWith(".ts"));
+  for (const source of sources) {
+    const input = execFileSync("git", ["show", `${baselineCommit}:${source}`], { cwd: root, encoding: "utf8" });
+    const output = ts.transpileModule(input, { compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext } }).outputText;
+    fs.writeFileSync(path.join(temporary, path.basename(source, ".ts") + ".js"), output);
+  }
+  const baselineClient = (await import(pathToFileURL(path.join(temporary, "bbradarClient.js")))).BBRadarClient;
+  const baselineServer = (await import(pathToFileURL(path.join(temporary, "server.js")))).createBbradarServer;
+  await new Promise((resolve) => api.listen(0, "127.0.0.1", resolve));
+  const config = {
+    apiKey: "fixture", apiBaseUrl: `http://127.0.0.1:${api.address().port}/api/v1`, webBaseUrl: "https://bbradar.io",
+    cacheTtlMs: 0, negativeCacheTtlMs: 0, cacheMaxEntries: 500, maxConcurrentRequests: 6,
+    defaultRateLimitPerMinute: 10000, exportRateLimitPerMinute: 10000,
+    compactToolText: true, toolProfile: "core", requestTimeoutMs: 5000, validateOnStartup: false
+  };
+  async function connect(ClientType, createServer) {
+    const upstream = new ClientType(config);
+    const server = createServer(upstream, config);
+    const client = new Client({ name: "revision-benchmark", version: "1" });
+    const [a, b] = InMemoryTransport.createLinkedPair();
+    await Promise.all([server.connect(b), client.connect(a)]);
+    const session = { client, server, upstream };
+    sessions.push(session);
+    return session;
+  }
+  const pair = [await connect(baselineClient, baselineServer), await connect(BBRadarClient, createBbradarServer)];
+  const workflows = [
+    ["search_programs", { page_size: 20 }],
+    ["get_program_targets", { program_id: "Platform:program-0", limit: 20 }],
+    ["find_programs", { platforms: ["Platform"], max_pages: 1, max_results: 10, include_target_samples: false }],
+    ["get_recent_changes", { page_size: 10 }],
+    ["find_hunt_targets", { platforms: ["Platform"], max_program_pages: 1, max_results: 10, targets_per_result: 5, upstream_request_budget: 20 }]
+  ];
+  const report = {};
+  for (const [name, args] of workflows) {
+    // Warm code and connections, then alternate revision order to reduce order bias.
+    for (const session of pair) for (let i = 0; i < 3; i += 1) await session.client.callTool({ name, arguments: args });
+    const samples = [[], []];
+    for (let i = 0; i < 30; i += 1) for (const index of i % 2 ? [1, 0] : [0, 1]) {
+      reset();
+      const started = performance.now();
+      const result = await pair[index].client.callTool({ name, arguments: args });
+      assert.equal(result.isError, undefined, `${name} revision ${index}`);
+      samples[index].push({ ms: performance.now() - started, requests: counts.requests, upstream_bytes: counts.bytes,
+        model_text_bytes: Buffer.byteLength(result.content[0].text), structured_bytes: Buffer.byteLength(JSON.stringify(result.structuredContent)) });
+    }
+    const summaries = samples.map((rows) => ({
+      samples: rows.length, requests_per_call: rows[0].requests, upstream_bytes: rows[0].upstream_bytes,
+      model_text_bytes: rows[0].model_text_bytes, structured_bytes: rows[0].structured_bytes,
+      p50_ms: round(percentile(rows.map((x) => x.ms), .5)), p95_ms: round(percentile(rows.map((x) => x.ms), .95))
+    }));
+    assert.equal(summaries[0].requests_per_call, summaries[1].requests_per_call, `${name}: upstream request regression`);
+    report[name] = { baseline: summaries[0], candidate: summaries[1], p50_change_percent: round((summaries[1].p50_ms / summaries[0].p50_ms - 1) * 100) };
+  }
+  const repeated = {};
+  for (const policy of ["public, max-age=30", "private, no-store"]) {
+    cacheControl = policy;
+    repeated[policy] = [];
+    for (const ClientType of [baselineClient, BBRadarClient]) {
+      const upstream = new ClientType({ ...config, cacheTtlMs: 30000 });
+      reset();
+      const started = performance.now();
+      for (let i = 0; i < 20; i += 1) await upstream.getProgram("Platform:program-0");
+      repeated[policy].push({ calls: 20, requests: counts.requests, duration_ms: round(performance.now() - started) });
+    }
+  }
+  cacheControl = "private, no-store";
+  const concurrency = [];
+  for (const session of pair) {
+    global.gc?.();
+    const heap = process.memoryUsage().heapUsed;
+    reset();
+    const started = performance.now();
+    for (let batch = 0; batch < 10; batch += 1) {
+      const results = await Promise.all(Array.from({ length: 20 }, (_, i) => session.client.callTool({ name: "search_programs", arguments: { search: `fixture-${batch}-${i}`, page_size: 20 } })));
+      assert.ok(results.every((result) => !result.isError));
+    }
+    const peakHeapDelta = process.memoryUsage().heapUsed - heap;
+    const elapsed = performance.now() - started;
+    global.gc?.();
+    assert.equal(session.upstream.diagnostics().in_flight_requests, 0);
+    assert.equal(session.upstream.diagnostics().request_concurrency.active, 0);
+    concurrency.push({ calls: 200, requests: counts.requests, peak_active: counts.peak, duration_ms: round(elapsed), heap_delta_before_gc: peakHeapDelta, retained_heap_delta: process.memoryUsage().heapUsed - heap });
+  }
+  const discovery = [];
+  for (const session of pair) {
+    const listed = await session.client.listTools();
+    discovery.push({ tools: listed.tools.length, bytes: Buffer.byteLength(JSON.stringify(listed)) });
+  }
+  process.stdout.write(JSON.stringify({ baseline_commit: baselineCommit, fixture: true, simulated_latency_ms: 5,
+    comparison: "Same inputs; caches disabled for common workflows. Array entries are baseline, candidate.",
+    workflows: report, repeated_reads: repeated, concurrency, discovery }, null, 2) + "\n");
+} finally {
+  for (const session of sessions) { await session.client.close(); await session.server.close(); }
+  api.close();
+  // Only remove the exact temporary directory created above, after unlinking its dependency junction.
+  if (path.dirname(temporary) !== path.resolve(os.tmpdir()) || !path.basename(temporary).startsWith("bbradar-compare-")) throw new Error("Unexpected temporary directory");
+  if (fs.existsSync(path.join(temporary, "node_modules"))) fs.unlinkSync(path.join(temporary, "node_modules"));
+  fs.rmSync(temporary, { recursive: true, force: true });
+}