@bbradar/mcp 0.2.6 → 0.3.0

package/dist/server.js

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { requiresActivityQuery } from "./activityContract.js";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BBRadarApiError } from "./bbradarClient.js";
@@ -6,7 +7,7 @@ import { NumericCursorStore } from "./cursorStore.js";
 import { stableStringify, stripUndefined } from "./json.js";
 import { FixedWindowRateLimiter } from "./rateLimit.js";
 import { readArray, readBoolean, readNumber, readObject, readString, sanitizeJson, sanitizeProPayload, sanitizeChange, sanitizeProgram, sanitizeRepositoryChange, sanitizeTarget, sanitizeTargetsForExport } from "./sanitize.js";
-const SERVER_VERSION = "0.2.6";
+const SERVER_VERSION = "0.3.0";
 const MAX_PROGRAMS_PER_SEARCH = 100;
 const MAX_TARGET_EXPORT = 500;
 const MAX_RECENT_CHANGES = 100;
@@ -71,7 +72,8 @@ const CORE_TOOL_NAMES = new Set([
     "get_program_activity",
     "get_analytics_platform_series",
     "get_analytics_program_activity",
-    "get_analytics_program_detail"
+    "get_analytics_program_detail",
+    "get_activity_capabilities", "get_activity_snapshot", "get_activity_rankings", "get_program_payouts", "get_activity_change_detail"
 ]);
 const TOOL_ENDPOINT_REQUIREMENTS = {
     search_targets: "target_search",
@@ -187,7 +189,7 @@ const changeListModeSchema = z.enum(["compact", "full"]);
 const repositoryChangeListModeSchema = z.enum(["compact", "full"]);
 const programListModeSchema = z.enum(["compact", "full"]);
 const rewardThresholdModeSchema = z.enum(["max_at_least", "min_at_least"]);
-const vdpModeSchema = z.enum(["include", "exclude", "only_likely", "only_known_no_bounty"]);
+const vdpModeSchema = z.enum(["include", "exclude", "only", "only_likely", "only_known_no_bounty"]);
 const targetMatchModeSchema = z
     .enum(["smart", "contains", "exact", "suffix", "wildcard"])
     .describe("How to match target_query. smart is forgiving for URLs, wildcards, target names, and partial words.");
@@ -283,6 +285,59 @@ const programSortSchema = z
     "best_hunt_value"
 ])
     .default("best_match");
+const ACTIVITY_TABS = ["payouts", "value", "scope", "rewards", "updates", "reports", "response", "status", "all_changes"];
+const ACTIVITY_EVENT_PERIODS = ["7d", "30d", "90d"];
+const ACTIVITY_COUNT_TABS = new Set(["payouts", "reports", "response"]);
+const ACTIVITY_SHARED_PARAMS = ["tab", "sort", "direction", "platforms", "tags", "program_kind", "program_type", "search",
+    "current_status", "labels", "opportunity_tiers", "cursor", "limit", "snapshot"];
+// Inputs the API accepts only for these views. Anything else is rejected before
+// a request so it cannot be silently ignored or reinterpreted.
+const ACTIVITY_TAB_PARAMS = {
+    payouts: ["period", "basis", "precision"],
+    value: ["include_map"],
+    scope: ["period"],
+    rewards: ["period"],
+    updates: ["period", "category"],
+    reports: ["period", "launched_within", "report_change_min", "report_change_max"],
+    response: ["period", "launched_within"],
+    status: ["period", "change_type"],
+    all_changes: ["period", "category"]
+};
+const activityCatalogSortSchema = z.enum(["updated", "payout_amount", "payout_lower_bound", "payout_upper_bound", "scope_added", "scope_net", "reward_change", "active_days", "reports", "reports_change", "resolved", "last_resolved", "first_response", "time_to_bounty", "last_change"]);
+const activityCountPeriodSchema = () => z.enum(["24h", "7d", "30d", "90d", "all_time"]);
+const activityEventPeriodSchema = () => z.enum(["7d", "30d", "90d"]);
+const activityCatalogNumberSchema = () => z.number().finite().min(0).optional();
+const activityCatalogInput = {
+    program_type: z.enum(["paid", "vdp", "unknown"]).optional(),
+    payout_metric: z.enum(["payout_total", "payout_increase", "payout_native_90d"]).optional(),
+    payout_period: activityCountPeriodSchema().optional(),
+    payout_precision: z.enum(["exact", "proven_bounds"]).optional(),
+    payout_min: activityCatalogNumberSchema(), payout_max: activityCatalogNumberSchema(),
+    payout_positive: z.boolean().optional().describe("true requires a proved positive payout; false requires an exact observed zero. Omit to include either."),
+    payout_activity: z.enum(["increase", "no_increase", "lower"]).optional(),
+    scope_period: activityEventPeriodSchema().optional(),
+    scope_added_min: activityCatalogNumberSchema(), scope_removed_min: activityCatalogNumberSchema(),
+    scope_net_min: z.number().finite().optional(), scope_net_max: z.number().finite().optional(),
+    reward_period: activityEventPeriodSchema().optional(),
+    reward_change: z.enum(["increased", "decreased"]).optional(), reward_change_min_pct: activityCatalogNumberSchema(),
+    updates_period: activityEventPeriodSchema().optional(),
+    active_days_min: activityCatalogNumberSchema(), changes_min: activityCatalogNumberSchema(),
+    change_category: z.enum(["scope", "rewards", "rules", "program"]).optional(),
+    reports_period: activityCountPeriodSchema().optional(),
+    reports_min: activityCatalogNumberSchema(), reports_max: activityCatalogNumberSchema(),
+    reports_change: z.enum(["rising", "falling"]).optional(), reports_change_min_pct: activityCatalogNumberSchema(),
+    launched_within: z.enum(["7d", "30d", "90d"]).optional(),
+    resolved_period: activityCountPeriodSchema().optional(), resolved_min: activityCatalogNumberSchema(),
+    last_resolved_within: z.enum(["7d", "30d", "90d"]).optional(),
+    first_response_max_hours: activityCatalogNumberSchema(), time_to_bounty_max_hours: activityCatalogNumberSchema(),
+    status_period: activityEventPeriodSchema().optional(),
+    status_change: z.enum(["first_seen", "paused", "resumed", "left_listing", "returned"]).optional(),
+    current_status: z.enum(["active", "paused", "suspended", "disabled", "closed", "unavailable", "unknown"]).optional(),
+    activity_labels: z.array(z.string().min(1).max(64)).max(10).optional(),
+    sort_by: activityCatalogSortSchema.optional(), sort_direction: z.enum(["asc", "desc"]).optional()
+};
+const activityCatalogGuidance = "Give each Activity signal its period (e.g. payout_period=30d with payout_positive=true; scope_period with scope_added_min) and use sort_by/sort_direction combinations enabled in get_activity_capabilities; default is updated descending. Tracked no_increase/lower require 30d. Nothing falls back to another period or precision.";
+const freeSubmissionOnlySchema = z.boolean().default(false).describe("Only programs with no detected submission fee or deposit.");
 const programIdSchema = z
     .string()
     .trim()
@@ -305,51 +360,24 @@ const programIdentifierSchema = z
 function jsonRecordSchema() {
     return z.record(z.unknown());
 }
-function rateLimitOutputSchema() {
-    return z.object({
-        remaining: z.number().int().min(0),
-        reset_at: z.string()
-    });
-}
-function toolTimingOutputSchema() {
-    return z.object({
-        tool_name: z.string(),
-        duration_ms: z.number().int().min(0)
-    });
-}
-function cacheOutputSchema() {
-    return z.object({
-        hit: z.boolean(),
-        stale_while_revalidate: z.boolean().optional(),
-        coalesced_live_request: z.boolean().optional(),
-        no_store: z.boolean().optional(),
-        expires_at: z.string().optional()
-    });
-}
-function errorOutputSchema() {
-    return z.object({
-        message: z.string(),
-        status: z.number().int().optional(),
-        detail: z.unknown().optional(),
-        errors: z.unknown().optional()
-    });
-}
 function programOutputSchema() {
     return jsonRecordSchema();
 }
+// Every tool repeats this envelope in discovery. Diagnostic objects (cache,
+// rate limit, timing, error) stay open records so each tool's schema stays small.
 function apiEnvelopeOutputShape() {
     return {
         request_id: z.string(),
         upstream_request_id: z.string().optional(),
         fetched_at: z.string().optional(),
-        cache: cacheOutputSchema().optional(),
+        cache: jsonRecordSchema().optional(),
         source_requests: z.array(jsonRecordSchema()).optional(),
-        mcp_rate_limit: rateLimitOutputSchema().optional(),
-        mcp_timing: toolTimingOutputSchema().optional(),
+        mcp_rate_limit: jsonRecordSchema().optional(),
+        mcp_timing: jsonRecordSchema().optional(),
         warnings: z.array(z.string()).optional(),
         program_id_resolution: jsonRecordSchema().optional(),
         recovery: jsonRecordSchema().optional(),
-        error: errorOutputSchema().optional()
+        error: jsonRecordSchema().optional()
     };
 }
 function programListOutputShape() {
@@ -367,7 +395,8 @@ function findProgramsOutputShape() {
         warnings: z.array(z.string()).optional(),
         errors: z.array(jsonRecordSchema()).optional(),
         upstream_budget: jsonRecordSchema().optional(),
-        ranking_scope: jsonRecordSchema().optional()
+        ranking_scope: jsonRecordSchema().optional(),
+        scan: jsonRecordSchema().optional()
     };
 }
 function decisionOutputShape() {
@@ -432,6 +461,8 @@ export function createBbradarServer(client, config) {
             "Use resolve_program or run_program_name_action for a named program.",
             "Use find_hunt_targets once for requests combining good rewards, broad scope, target quality, and recent target additions. Use find_repository_hunt_targets instead when Git or repository activity is explicitly required.",
             "Use find_programs for lower-level program-only discovery and find_programs_by_target for reverse target lookup.",
+            "For payouts, reports, response measures or Activity comparisons, first read get_activity_capabilities, then get_activity_rankings with the matching tab for one ranking. For several conditions at once (e.g. recent payouts plus new scope, Web2-only, low competition, no submission fee) use one find_hunt_targets or find_programs call with Activity inputs and local filters together. Keep periods explicit; never intersect separately paginated rankings.",
+            "Activity data is published in versions. get_activity_snapshot reports the current version; pass its snapshot_id as snapshot to bind capabilities and first pages to one version, and never mix rows from different versions.",
             "For semantic changes use get_history_changes or get_program_history, then get_history_change_detail only when before/after items are needed. For exact activity use get_program_activity; for ranked activity use get_analytics_program_activity. Use daily analytics tools directly for date series.",
             "Default to bounty-eligible in-scope data unless the user explicitly requests broader results.",
             "Prefer compact/identifier outputs and disclose sampled ranking scope when present."
@@ -442,6 +473,8 @@ export function createBbradarServer(client, config) {
             "Simple default path: find_hunt_targets once for ranked target/program discovery, run_program_name_action for one named program, get_program_eligible_targets_by_name for exhaustive target lists by program name.",
             "Do not repeat program discovery with alternate sorts or fan out get_program_targets across a shortlist; find_hunt_targets already includes exact bounded samples and recent target additions.",
             "Use advanced tools only after the user's goal is clear or the guide points to them.",
+            "For payouts, reports, response measures or Activity comparisons, first read get_activity_capabilities. Use get_activity_rankings (or its per-view alias) for one ranking, or one find_hunt_targets/find_programs call combining Activity inputs with Web2, scope, competition and fee filters. Keep server order and explicit periods; never re-rank a sampled catalog or intersect separate pages.",
+            "Activity data is published in versions. get_activity_snapshot reports the current version; pass its snapshot_id as snapshot to bind capabilities and first pages to one version, and never mix rows from different versions.",
             "Partial program name + action: run_program_name_action. Partial program name only: resolve_program.",
             "Default to bounty-eligible in-scope data. Include out-of-scope, ineligible, VDP, disclosure-only, or no-bounty data only when the user explicitly asks.",
             "Recently updated programs across platforms: find_recently_updated_programs. Do not infer a platform such as Immunefi unless the user explicitly names it.",
@@ -478,6 +511,135 @@ export function createBbradarServer(client, config) {
     const targetSearchPageSizeSchema = z.number().int().min(1).max(maxTargetSearchPageSize).default(Math.min(50, maxTargetSearchPageSize));
     const historyOutput = { ...apiEnvelopeOutputShape(), changes: z.array(jsonRecordSchema()).optional(), coverage: jsonRecordSchema().optional(), meta: jsonRecordSchema().optional() };
     const analyticsOutput = { ...apiEnvelopeOutputShape(), platform: z.string().optional(), program: jsonRecordSchema().optional(), programs: z.array(jsonRecordSchema()).optional(), series: z.array(jsonRecordSchema()).optional(), observations: jsonRecordSchema().optional(), category: z.string().optional(), population: z.string().optional(), ranking_definition: z.string().optional(), inventory_definition: z.string().optional(), meta: jsonRecordSchema().optional() };
+    // Published Activity versions are 64 lowercase hex characters. "start" and
+    // catalog snapshot tokens are different contracts and are rejected here.
+    const activitySnapshotSchema = z.string().regex(/^[0-9a-f]{64}$/, "Use a snapshot_id returned by Activity.")
+        .describe("Published Activity version (get_activity_snapshot or meta.snapshot_id). Binds reads to one version; expired or withdrawn versions return 410. Never mix with a cursor from another version.");
+    const includeMapSchema = z.boolean().default(false)
+        .describe("Return Value map points (up to thousands). Off by default: map_points_omitted reports the count.");
+    const activityParams = {
+        tab: z.enum(ACTIVITY_TABS),
+        period: z.enum(["24h", "7d", "30d", "90d", "all_time"]).optional(),
+        basis: z.enum(["reported", "tracked"]).optional(),
+        precision: z.enum(["exact", "proven_bounds"]).optional(),
+        sort: z.string().min(1).max(64).optional(),
+        direction: z.enum(["asc", "desc"]).optional(),
+        platforms: platformListSchema(), tags: tagListSchema(),
+        program_kind: z.enum(["bounty", "contest", "audit", "challenge"]).optional(),
+        program_type: z.enum(["paid", "vdp", "unknown"]).optional(),
+        search: z.string().min(1).max(200).optional(),
+        current_status: z.enum(["active", "paused", "suspended", "disabled", "closed", "unavailable", "unknown"]).optional(),
+        labels: z.array(z.string().min(1).max(64)).max(10).optional().describe("Only labels listed by get_activity_capabilities; others return 422."),
+        opportunity_tiers: z.array(opportunityLevelSchema).min(1).max(4).optional().describe("Any of these catalog opportunity tiers, as frozen into the Activity version. get_activity_capabilities lists the tiers present in facets.opportunity_tiers; an API without the filter is rejected before any request."),
+        launched_within: z.enum(["7d", "30d", "90d"]).optional(),
+        category: z.enum(["scope", "rewards", "rules", "program"]).optional(),
+        change_type: z.enum(["first_seen", "paused", "resumed", "left_listing", "returned"]).optional(),
+        report_change_min: z.number().finite().optional(), report_change_max: z.number().finite().optional(),
+        include_map: includeMapSchema,
+        cursor: opaqueCursorSchema.optional(), limit: proLimitSchema.default(25),
+        snapshot: activitySnapshotSchema.optional()
+    };
+    const activityOutput = {
+        ...apiEnvelopeOutputShape(), rows: z.array(jsonRecordSchema()).optional(), points: z.array(jsonRecordSchema()).optional(),
+        tab: z.string().optional(), period: z.string().nullable().optional(),
+        basis: z.string().nullable().optional(), precision: z.string().nullable().optional(),
+        sort: z.string().nullable().optional(), direction: z.string().optional(), meta: jsonRecordSchema().optional(),
+        cohort_median: jsonRecordSchema().nullable().optional(), available_views: z.array(jsonRecordSchema()).optional(),
+        map_points_omitted: z.number().int().optional()
+    };
+    registerTool("get_activity_capabilities", {
+        title: "Get Available Activity Views",
+        description: "Read the exact enabled period, sort, direction, basis and precision combinations before choosing an Activity ranking. Availability is evaluated before user filters; do not infer combinations from independent enums. Honor each view's sort_directions and default_direction and the enabled label list. The snapshot block identifies the published version these capabilities belong to.",
+        inputSchema: z.object({ snapshot: activitySnapshotSchema.optional() }).strict(),
+        outputSchema: { ...apiEnvelopeOutputShape(), tabs: z.array(jsonRecordSchema()).optional(), version: z.union([z.string(), z.number()]).optional(), facets: jsonRecordSchema().optional(), labels: z.array(z.string()).optional(), listing: jsonRecordSchema().optional(), listing_payouts_enabled: z.boolean().optional(), derived_signals_enabled: z.boolean().optional(), snapshot: jsonRecordSchema().optional() },
+        annotations: readOnlyAnnotations
+    }, (args) => runTool("get_activity_capabilities", config, rateLimiter, async () => {
+        assertProFeature(client, "activity_capabilities", "enabled");
+        assertActivitySnapshotSelector(client, "activity_capabilities", args.snapshot);
+        return proPage(await client.getActivityCapabilities(toQuery({ snapshot: args.snapshot })), "tabs");
+    }));
+    registerTool("get_activity_snapshot", {
+        title: "Get Current Activity Version",
+        description: "Read only the identity of the currently published Activity version: snapshot_id, frozen as_of cutoff, expires_at, policy_version and suggested poll_seconds. Use it to detect newer Activity data and pass snapshot_id as snapshot to bind capabilities, first pages and payouts to one version. as_of is when BBRadar froze its calculation, not a provider payment or update time.",
+        inputSchema: z.object({}).strict(),
+        outputSchema: { ...apiEnvelopeOutputShape(), snapshot_id: z.string().optional(), as_of: z.string().optional(), expires_at: z.string().optional(), policy_version: z.string().optional(), poll_seconds: z.number().optional() },
+        annotations: readOnlyAnnotations
+    }, () => runTool("get_activity_snapshot", config, rateLimiter, async () => {
+        assertProFeature(client, "activity_snapshot", "enabled");
+        const api = await client.getActivitySnapshot();
+        const data = readObject(api.data);
+        if (!data || typeof data.snapshot_id !== "string" || !/^[0-9a-f]{64}$/.test(data.snapshot_id)) {
+            throw new Error("Malformed Activity version response.");
+        }
+        return withApiMetadata(api, sanitizeProPayload(api.data));
+    }));
+    registerTool("get_program_payouts", {
+        title: "Get Program Payouts and Response Facts",
+        description: "Read reported totals, measured counter increases, source dates, precision, report and response facts, derived signals and label explanations for one exact platform:handle. Keep null separate from zero, bounds separate from exact amounts and unknown payment dates null. Payout timestamps are when increases were seen, never payment dates. No provider requests are made.",
+        inputSchema: z.object({ program_id: programIdSchema, snapshot: activitySnapshotSchema.optional(), include_map: includeMapSchema }).strict(),
+        // Mirrors the API response, including its version identity: a client that
+        // discovered this schema validates every structured result against it.
+        outputSchema: { ...apiEnvelopeOutputShape(), program_id: z.string().optional(), program: jsonRecordSchema().optional(), summary: jsonRecordSchema().optional(), as_of: z.string().optional(), snapshot_id: z.string().optional(), expires_at: z.string().nullable().optional(), facts: z.array(jsonRecordSchema()).optional(), windows: jsonRecordSchema().optional(), series: z.array(jsonRecordSchema()).optional(), payout_summary: jsonRecordSchema().nullable().optional(), views: z.array(jsonRecordSchema()).optional(), reports: jsonRecordSchema().optional(), response: jsonRecordSchema().optional(), last_increase_at: z.string().nullable().optional(), signals: jsonRecordSchema().optional(), label_details: z.array(jsonRecordSchema()).optional(), labels: z.array(z.string()).optional(), value_points: z.array(jsonRecordSchema()).optional(), map_points_omitted: z.number().int().optional(), meta: jsonRecordSchema().optional() },
+        annotations: readOnlyAnnotations
+    }, (args) => runTool("get_program_payouts", config, rateLimiter, async () => {
+        assertProFeature(client, "program_payouts", "enabled");
+        assertActivitySnapshotSelector(client, "program_payouts", args.snapshot);
+        const api = await client.getProgramPayouts(args.program_id, toQuery({ snapshot: args.snapshot }));
+        if (!readObject(api.data))
+            throw new Error("Malformed program payout response.");
+        return omitMapPoints(withApiMetadata(api, sanitizeProPayload(api.data)), "value_points", args.include_map);
+    }));
+    const readActivityRanking = async (tab, args) => {
+        assertProFeature(client, "activity_rankings", "enabled");
+        assertActivitySnapshotSelector(client, "activity_rankings", args.snapshot);
+        assertActivityTierFilter(client, args.opportunity_tiers);
+        const { include_map, ...query } = args;
+        return activityRankingPage(await client.getActivityRankings(toQuery({ ...query, tab })), include_map === true);
+    };
+    registerTool("get_activity_rankings", {
+        title: "Get Activity Ranking",
+        description: "One globally ranked server page of an Activity view, frozen at meta.as_of. Read get_activity_capabilities first: explicit period/basis/precision/sort/direction never fall back, and each tab only accepts its own inputs. tab: payouts (reported and tracked bases stay separate; proven_bounds desc = highest reported minimum, asc = lowest reported maximum, never an exact ranking; source totals can lag); value (fixed lifetime generosity and 90-day volume percentiles, no period; one label gives its shortlist); scope (recorded additions/removals/net, not inventory differences); rewards (net reward-range change, unknown % stays null); updates (active UTC days, change groups); reports (received counts; volume is not competition; all_time is the lifetime counter); response (resolved counts, last resolution, response time; time to bounty is award timing); status (first_seen/paused/resumed/left_listing/returned events); all_changes (chronological events; get_activity_change_detail for before/after). Event tabs use rolling 7d/30d/90d, not calendar months. launched_within applies to reports/response. Payout increases are observed counters, not payment dates. Reuse cursors only with identical inputs. For several signals at once, or with Web2/scope/competition/fee filters, use find_programs or find_hunt_targets.",
+        inputSchema: z.object(activityParams).strict(),
+        outputSchema: activityOutput,
+        annotations: readOnlyAnnotations
+    }, (args) => runTool("get_activity_rankings", config, rateLimiter, async () => {
+        assertActivityTabInputs(args.tab, args);
+        return readActivityRanking(args.tab, args);
+    }));
+    // Single-view aliases for the full profile; each schema exposes only the
+    // inputs its view accepts and shares the ranking tool's request path.
+    const activityDescriptions = {
+        value: "Discover programs with frozen within-platform value and report-volume percentiles. Generosity is lifetime; volume is 90 days. No period or launch-cohort input applies. Use a label-specific shortlist: Pays near top orders by realization, No payouts seen by received_90d (raw count with its basis; small cohorts remain eligible). Comparative ratio sorts use server percentiles; never recompute after filtering. Preserve label_details explanations and destinations. A counter increase is observed activity, not an individual payment. Map points are returned only with include_map.",
+        payouts: "Rank payouts using the same server calculation as BBRadar. Last 7 days and last 30 days are rolling windows. Explicit periods never fall back. For high or low payouts lately, use the same enabled tracked-30-day cohort, or separately label a native-90-day cohort. Reported and tracked bases stay separate. With proven_bounds, descending is Highest reported minimum using lower bounds; ascending is Lowest reported maximum using upper bounds. Neither claims an exact ranking. Source totals can be delayed, including Immunefi.",
+        scope: "Rank recorded scope additions, removals, net movement or largest update; not differences between inventory totals. Periods are rolling 7, 30 or 90 days, not calendar months.",
+        rewards: "Rank comparable net reward-range changes over rolling 7, 30 or 90 days. Unknown change percentages remain null.",
+        updates: "Rank active UTC days and recorded change groups over rolling periods. Baselines and internal corrections are excluded.",
+        reports: "Rank received report counts. Each program uses measured lifetime-counter growth where available, otherwise its supported native period. All-time is the current lifetime counter. Previous and change compare like-for-like. Report volume is not competition. Launch cohorts use the canonical launch date; amounts are not reports since launch.",
+        response: "Rank resolved counter growth or current lifetime counters, last resolution, response duration or time to bounty. Keep the provider's definition: time to bounty is award timing, not payment settlement. Period applies only to resolved counts.",
+        status: "Read distinct First seen, Paused, Resumed, Left listing and Returned events. Event type and current status are separate filters; never merge events from one program.",
+        all_changes: "Read chronological semantic program changes with event IDs. Fetch get_activity_change_detail lazily for before/after items, including eligible events for programs that left the catalog. Separate events stay separate."
+    };
+    for (const tab of ACTIVITY_TABS) {
+        const name = `get_activity_${tab === "all_changes" ? "changes" : tab}`;
+        const allowed = new Set([...ACTIVITY_SHARED_PARAMS, ...ACTIVITY_TAB_PARAMS[tab]]);
+        const shape = Object.fromEntries(Object.entries(activityParams).filter(([key]) => key !== "tab" && allowed.has(key)));
+        if (!ACTIVITY_COUNT_TABS.has(tab) && shape.period)
+            shape.period = z.enum(ACTIVITY_EVENT_PERIODS).optional();
+        registerTool(name, {
+            title: `Get Activity ${tab === "all_changes" ? "Changes" : tab[0].toUpperCase() + tab.slice(1)}`,
+            description: `${activityDescriptions[tab]} One globally ranked server page, with a frozen as-of cutoff. Reuse cursors only with unchanged filters. Use get_activity_capabilities for supported combinations.`,
+            inputSchema: z.object(shape).strict(), outputSchema: activityOutput, annotations: readOnlyAnnotations
+        }, (args) => runTool(name, config, rateLimiter, () => readActivityRanking(tab, args)));
+    }
+    registerTool("get_activity_change_detail", {
+        title: "Get Activity Change Detail",
+        description: "Read one bounded page of recorded before/after items for an exact Activity event ID in its source snapshot. Pass meta.snapshot_id from the Activity page. Retained eligible events may describe programs that have left the catalog. Reuse an opaque cursor only with the same event, snapshot and limit.",
+        inputSchema: z.object({ event_id: z.string().min(1).max(128), snapshot: activitySnapshotSchema.describe("meta.snapshot_id from the Activity page that supplied this event."), cursor: opaqueCursorSchema.optional(), limit: proLimitSchema.default(50) }).strict(),
+        outputSchema: { ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }, annotations: readOnlyAnnotations
+    }, (args) => runTool("get_activity_change_detail", config, rateLimiter, async () => {
+        assertProFeature(client, "activity_event_detail", "enabled");
+        return proPage(await client.getActivityChangeDetail(args.event_id, toQuery({ snapshot: args.snapshot, cursor: args.cursor, limit: args.limit })), "items");
+    }));
     registerTool("get_history_changes", {
         title: "Get Program History Changes",
         description: "One page of semantic program History. Use get_program_history for an exact program, especially Self-Hosted. History may be partial or unavailable; inspect coverage.",
@@ -554,8 +716,8 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("search_programs", {
         title: "Search BBRadar Programs",
-        description: `Search or list active and confirmed paused platform programs plus active Self-Hosted programs. page_size max ${maxProgramsPageSize}. Stable snapshots are opt-in because creating one can be slower than live indexed pagination.`,
-        inputSchema: {
+        description: `Search or list active and confirmed paused platform programs plus active Self-Hosted programs. page_size max ${maxProgramsPageSize}. Stable snapshots are opt-in. For payout, report, scope-change or other Activity filters use find_programs.`,
+        inputSchema: z.object({
             search: searchTextSchema.optional().describe("Server-side program name, handle, platform, policy-host, or target search."),
             program_kind: z.enum(["bounty", "contest", "challenge"]).optional(),
             platforms: platformListSchema(),
@@ -565,7 +727,7 @@ export function createBbradarServer(client, config) {
             vdp_mode: vdpModeSchema.default("exclude").describe("VDP/no-bounty filter mode."),
             page: pageSchema,
             page_size: programsPageSizeSchema
-        },
+        }).strict(),
         outputSchema: programListOutputShape(),
         annotations: readOnlyAnnotations
     }, (args) => runTool("search_programs", config, rateLimiter, async () => {
@@ -924,8 +1086,9 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("find_hunt_targets", {
         title: "Find Best Hunt Targets",
-        description: "Preferred one-call path for requests combining good rewards, broad Web2/Web3 scope, target quality, competition, and recently added targets. Returns a final ranked shortlist with exact bounded target samples and recent additions; do not fan out into repeated find_programs/get_program_targets calls. Self-Hosted is supported through current inventory and automatically skips its unavailable change feed. Use find_repository_hunt_targets instead only when Git or repository activity is explicitly requested.",
-        inputSchema: {
+        description: "Preferred one-call path for requests combining good rewards, broad Web2/Web3 scope, target quality, competition, recent payouts or scope changes, and recently added targets. Activity inputs (e.g. payout_period=30d with payout_positive=true, scope_period=30d with scope_added_min=1) first narrow candidates on the server in global order; the other filters and ranking_mode then apply locally. Returns a final ranked shortlist with exact bounded target samples and recent additions; do not fan out into repeated find_programs/get_program_targets calls. Self-Hosted is supported through current inventory and automatically skips its unavailable change feed. Use find_repository_hunt_targets instead only when Git or repository activity is explicitly requested.",
+        inputSchema: z.object({
+            ...activityCatalogInput,
             platforms: platformListSchema(),
             exclude_platforms: stringListSchema("Platforms to exclude from the final shortlist."),
             tags: tagListSchema(),
@@ -952,9 +1115,10 @@ export function createBbradarServer(client, config) {
             max_program_pages: z.number().int().min(1).max(MAX_FIND_PROGRAM_PAGES).default(DEFAULT_HUNT_PROGRAM_PAGES),
             max_results: z.number().int().min(1).max(MAX_HUNT_RESULTS).default(10),
             targets_per_result: z.number().int().min(1).max(MAX_HUNT_TARGETS_PER_RESULT).default(5),
+            free_submission_only: freeSubmissionOnlySchema,
             ranking_mode: z.enum(["balanced", "highest_reward", "widest_scope", "freshest_targets", "lowest_competition"]).default("balanced"),
             upstream_request_budget: z.number().int().min(2).max(MAX_FIND_UPSTREAM_REQUEST_BUDGET).default(DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET)
-        },
+        }).strict(),
         outputSchema: {
             ...apiEnvelopeOutputShape(),
             matches: z.array(jsonRecordSchema()).optional(),
@@ -962,11 +1126,15 @@ export function createBbradarServer(client, config) {
             errors: z.array(jsonRecordSchema()).optional(),
             upstream_budget: jsonRecordSchema().optional(),
             ranking_scope: jsonRecordSchema().optional(),
+            scan: jsonRecordSchema().optional(),
             result_guidance: jsonRecordSchema().optional(),
             meta: jsonRecordSchema().optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("find_hunt_targets", config, rateLimiter, async () => findHuntTargets(client, config, args)));
+    }, (args) => runTool("find_hunt_targets", config, rateLimiter, async () => {
+        const activity = Object.fromEntries(Object.keys(activityCatalogInput).map((key) => [key, args[key]]));
+        return findHuntTargets(client, config, args, activity);
+    }));
     registerTool("find_repository_hunt_targets", {
         title: "Find Repository-Aware Hunt Targets",
         description: "Fast one-call path for requests that combine recent repository activity with program rewards and target quality. Fetches program rankings and repository changes in parallel, joins them locally, and works with arbitrary supported platform catalogs, Web2/Web3 modes, reward thresholds, target types, languages, and freshness criteria. Self-Hosted has no repository stream and is rejected without upstream work.",
@@ -1184,16 +1352,19 @@ export function createBbradarServer(client, config) {
     }, (args) => runTool("check_watchlist_new_targets", config, rateLimiter, async () => checkWatchlistNewTargets(client, config, args)));
     registerTool("get_opportunities", {
         title: "Get BBRadar Opportunities",
-        description: `List programs in one opportunity tier. page_size max ${MAX_PROGRAMS_PER_SEARCH}.`,
-        inputSchema: {
+        description: `List programs in one opportunity tier. page_size max ${MAX_PROGRAMS_PER_SEARCH}. For Activity filters within a tier use find_programs with one opportunity_levels entry.`,
+        inputSchema: z.object({
             level: opportunityLevelSchema.default("elite"),
+            program_kind: z.enum(["bounty", "contest", "challenge"]).optional(),
+            search: searchTextSchema.optional(),
             platforms: platformListSchema(),
             tags: tagListSchema(),
             updated_since: isoDateTimeSchema.optional(),
+            snapshot: stableSnapshotSchema.optional(),
             vdp_mode: vdpModeSchema.default("exclude").describe("VDP/no-bounty filter mode."),
             page: pageSchema,
             page_size: programsPageSizeSchema
-        },
+        }).strict(),
         outputSchema: {
             ...programListOutputShape(),
             level: opportunityLevelSchema.optional()
@@ -1201,11 +1372,15 @@ export function createBbradarServer(client, config) {
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_opportunities", config, rateLimiter, async () => {
         const { level, vdp_mode, ...filters } = args;
-        const api = await client.getOpportunities(level, toQuery(filters));
+        assertStableSnapshotSupported(client, "opportunities", filters.snapshot);
+        const combined = args.program_kind !== undefined;
+        if (combined)
+            assertCatalogQuerySupported(client, "opportunities", args);
+        const api = await client.getOpportunities(level, toQuery({ ...filters, vdp_mode: combined ? vdp_mode : undefined }));
         const data = readObject(api.data);
         const programs = readArray(data?.programs)
             .map((program) => toProgramCandidate(program, config.webBaseUrl))
-            .filter((candidate) => candidateMatchesVdpMode(candidate, vdp_mode))
+            .filter((candidate) => combined || candidateMatchesVdpMode(candidate, vdp_mode))
             .map((candidate) => candidate.program);
         return withApiMetadata(api, {
             level,
@@ -1215,8 +1390,12 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("find_programs", {
         title: "Find BBRadar Programs",
-        description: "Lower-level program-only discovery. For normal 'find good targets/programs' requests, prefer one find_hunt_targets call because it already combines ranking, exact bounded target samples, and recent additions. Use this tool when raw program filtering without target enrichment is specifically needed; keep output_mode=compact and avoid parallel alternate-sort calls.",
-        inputSchema: {
+        description: `Program discovery. Activity inputs (payouts, reports, scope/reward changes, response, status, labels) run on the server over the complete catalog in one global order, within at most one opportunity tier. They combine freely with local filters (Web2/Web3, wildcards, target counts, bounty, competition_risks, report counts, free_submission_only, freshness): pages are read in server order and local filters only remove programs; scan.complete and scan.next_cursor report coverage. Sampled sorts need no Activity inputs. ${activityCatalogGuidance}`,
+        inputSchema: z.object({
+            ...activityCatalogInput,
+            search: searchTextSchema.optional(),
+            snapshot: stableSnapshotSchema.optional(),
+            page: z.number().int().min(1).optional(),
             platforms: platformListSchema(),
             exclude_platforms: stringListSchema("Platforms to exclude after retrieval. Use list_filters first when the user asks for a geographic/platform exclusion without naming exact platform values."),
             tags: tagListSchema(),
@@ -1226,6 +1405,9 @@ export function createBbradarServer(client, config) {
             web3: z.boolean().default(false).describe("Require Web3 signals."),
             program_kind: z.enum(["bounty", "contest", "challenge"]).optional().describe("Source-classified program kind; sent to the Pro program list."),
             exclude_web3: z.boolean().default(false).describe("Exclude programs with Web3, blockchain, smart-contract, crypto, DeFi, NFT, Solidity, Ethereum, or Solana signals. Use this for Web2-only discovery."),
+            free_submission_only: freeSubmissionOnlySchema,
+            competition_risks: z.array(competitionRiskSchema).max(4).default([]).describe("Program competition labels to keep, e.g. [\"Low\"]."),
+            cursor: z.string().min(1).max(512).optional().describe("scan.next_cursor from the previous result; repeat the same filters."),
             opportunity_levels: z.array(opportunityLevelSchema).max(4).default([]),
             updated_since: isoDateTimeSchema.optional(),
             min_bounty_min: z.number().int().min(0).optional(),
@@ -1249,7 +1431,7 @@ export function createBbradarServer(client, config) {
             min_added_7d: z.number().int().min(0).optional(),
             max_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
             max_results: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(10),
-            sort_by: programSortSchema,
+            sort_by: z.union([programSortSchema.removeDefault(), activityCatalogSortSchema]).optional(),
             include_target_samples: z.boolean().default(false),
             target_sample_programs: z.number().int().min(0).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
             target_sample_size: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(5),
@@ -1257,13 +1439,40 @@ export function createBbradarServer(client, config) {
             only_bounty_eligible_targets: z.boolean().default(true),
             output_mode: programListModeSchema.default("compact"),
             upstream_request_budget: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET)
-        },
+        }).strict(),
         outputSchema: findProgramsOutputShape(),
         annotations: readOnlyAnnotations
-    }, (args) => runTool("find_programs", config, rateLimiter, async () => findPrograms(client, config, {
-        ...args,
-        target_samples_only_wildcards: args.min_wildcards > 0
-    })));
+    }, (args) => runTool("find_programs", config, rateLimiter, async () => {
+        const serverCatalog = hasActivityCatalogInput(args) || args.snapshot !== undefined || args.page !== undefined || args.cursor !== undefined
+            || (args.search !== undefined && supportsCatalogFilters(client, args.opportunity_levels.length ? "opportunities" : "programs")
+                && !legacyCatalogFilters(args).length && ["include", "exclude", "only"].includes(args.vdp_mode));
+        if (serverCatalog && args.cursor === undefined && !legacyCatalogFilters(args).length)
+            return findServerCatalogPrograms(client, config, args);
+        if (serverCatalog) {
+            // Platform, tag, kind, VDP, update and status predicates were applied
+            // by the server; only the remaining filters run locally.
+            return findFilteredServerPrograms(client, config, args, {
+                ...args, sort_by: "best_match", platforms: [], tags: [], program_kind: undefined, contest_like: false,
+                vdp_mode: "include", opportunity_levels: [], updated_since: undefined, skip_status_check: true,
+                min_bounty_min: args.min_bounty_min, min_bounty_max: args.min_bounty_max, max_bounty_max: args.max_bounty_max,
+                max_public_report_count: args.max_public_report_count, fresh_launch_days: args.fresh_launch_days,
+                min_eligible_targets: args.min_eligible_targets, min_total_targets: args.min_total_targets,
+                min_added_24h: args.min_added_24h, min_added_7d: args.min_added_7d,
+                target_samples_only_wildcards: args.min_wildcards > 0
+            });
+        }
+        return findPrograms(client, config, {
+            ...args,
+            updated_since: args.updated_since,
+            min_bounty_min: args.min_bounty_min, min_bounty_max: args.min_bounty_max,
+            max_bounty_max: args.max_bounty_max, max_public_report_count: args.max_public_report_count,
+            fresh_launch_days: args.fresh_launch_days,
+            min_eligible_targets: args.min_eligible_targets, min_total_targets: args.min_total_targets,
+            min_added_24h: args.min_added_24h, min_added_7d: args.min_added_7d,
+            sort_by: programSortSchema.parse(args.sort_by),
+            target_samples_only_wildcards: args.min_wildcards > 0
+        });
+    }));
     registerTool("find_wildcard_programs", {
         title: "Find Wildcard Programs",
         description: "Wildcard program shortlist with platform, minimum reward, freshness, and report-count filters.",
@@ -2177,6 +2386,9 @@ function bbradarGuide(topic, profile, client) {
             arguments: { include_targets: false, max_cursor_pages: 2 },
             then: "For incremental polling, seed once with after_id and later set resume_cursor=true with the same filters."
         },
+        { user_goal: "program payouts, recent reports, response times or Activity rankings", first_tool: "get_activity_capabilities", arguments: {}, then: "Choose an enabled period, sort and direction, then call get_activity_rankings with that tab for one server-ranked page. Do not approximate by paging or re-ranking the catalog." },
+        { user_goal: "programs with recent payouts and new scope that also match Web2, competition or fee criteria", first_tool: "find_hunt_targets", arguments: { payout_period: "30d", payout_positive: true, scope_period: "30d", scope_added_min: 1, surface_mode: "web2", free_submission_only: true, ranking_mode: "lowest_competition" }, then: "Use find_programs with the same Activity inputs and competition_risks for program-only results; continue with scan.next_cursor." },
+        { user_goal: "payout and report facts for one exact program", first_tool: "get_program_payouts", arguments: { program_id: "Platform:handle" } },
         { user_goal: "semantic program change history", first_tool: "get_program_history", arguments: { program_id: "Platform:handle" }, then: "Fetch get_history_change_detail only for a selected change." },
         { user_goal: "most active programs in a date range", first_tool: "get_analytics_program_activity", arguments: {}, then: "Use this server-side ranking rather than sampling the program catalog." },
         { user_goal: "exact recorded activity for one program", first_tool: "get_program_activity", arguments: { program_id: "Platform:handle" } },
@@ -2322,6 +2534,9 @@ function coreBbradarGuide(topic, client) {
             first_tool: "get_repository_changes",
             arguments: { include_targets: false, max_cursor_pages: 2 }
         },
+        { user_goal: "program payouts, recent reports, response times or Activity rankings", first_tool: "get_activity_capabilities", arguments: {}, then: "Read supported view combinations and call get_activity_rankings with that tab. Use get_activity_change_detail lazily for a selected Activity event." },
+        { user_goal: "programs with recent payouts and new scope that also match Web2, competition or fee criteria", first_tool: "find_hunt_targets", arguments: { payout_period: "30d", payout_positive: true, scope_period: "30d", scope_added_min: 1, surface_mode: "web2", free_submission_only: true, ranking_mode: "lowest_competition" } },
+        { user_goal: "payout and report facts for one exact program", first_tool: "get_program_payouts", arguments: { program_id: "Platform:handle" } },
         { user_goal: "semantic program change history", first_tool: "get_program_history", arguments: { program_id: "Platform:handle" }, then: "Fetch change detail only when needed." },
         { user_goal: "most active programs", first_tool: "get_analytics_program_activity", arguments: {} },
         { user_goal: "exact recorded activity", first_tool: "get_program_activity", arguments: { program_id: "Platform:handle" } },
@@ -6040,6 +6255,9 @@ function compactProgram(program) {
         competition_risk: stringField(program, "competition_risk"),
         competition_risk_reason: stringField(program, "competition_risk_reason"),
         submission_cost: program.submission_cost,
+        payout_summary: program.payout_summary,
+        activity: program.activity,
+        activity_summary: program.activity_summary,
         reward_range: program.reward_range,
         reward_range_label: stringField(program, "reward_range_label"),
         public_report_count: program.public_report_count,
@@ -6598,7 +6816,10 @@ function clampLimit(name, value, max, warnings) {
     warnings.push(`${name} was clamped from ${value} to ${max}.`);
     return max;
 }
-async function findHuntTargets(client, config, input) {
+// Candidate pool for hunts narrowed by Activity on the server. Matches arrive in
+// server order, so a larger pool lets ranking_mode choose among more of them.
+const HUNT_SERVER_POOL = 100;
+async function findHuntTargets(client, config, input, activity = {}) {
     const warnings = [];
     const errors = [];
     const selfHostedOnly = isSelfHostedOnlyPlatformSelection(input.platforms);
@@ -6641,6 +6862,7 @@ async function findHuntTargets(client, config, input) {
         min_total_targets: input.min_total_targets,
         min_added_24h: undefined,
         min_added_7d: input.min_added_7d,
+        free_submission_only: input.free_submission_only,
         max_pages: input.max_program_pages,
         max_results: candidatePoolSize,
         sort_by: huntProgramSort(input.ranking_mode),
@@ -6662,8 +6884,17 @@ async function findHuntTargets(client, config, input) {
     else if (recentChangeQueries.length < desiredRecentChangeQueries.length) {
         warnings.push(`Recent target-change queries were reduced from ${desiredRecentChangeQueries.length} to ${recentChangeQueries.length} to preserve the upstream request budget.`);
     }
+    const serverFiltered = hasActivityCatalogInput(activity);
     const [programPayload, recentResult] = await Promise.all([
-        findPrograms(client, config, programInput),
+        serverFiltered
+            ? findFilteredServerPrograms(client, config, {
+                ...programInput, ...activity, opportunity_levels: [], sort_by: activity.sort_by, sort_direction: activity.sort_direction,
+                platforms: input.platforms, tags: input.tags, updated_since: input.updated_since, vdp_mode: "exclude", include_target_samples: false
+            }, {
+                ...programInput, platforms: [], tags: [], vdp_mode: "include", updated_since: undefined,
+                max_pages: programRequestBudget, upstream_request_budget: programRequestBudget
+            }, HUNT_SERVER_POOL)
+            : findPrograms(client, config, programInput),
         recentChangesEnabled
             ? fetchHuntRecentChanges(client, config, input, recentChangeQueries)
             : Promise.resolve({ changes: [], sourceRequests: [], requestsUsed: 0, errors: [] })
@@ -6733,6 +6964,8 @@ async function findHuntTargets(client, config, input) {
             min_target_score: input.min_target_score,
             target_opportunity_label: input.target_opportunity_label,
             competition_risk: input.competition_risk,
+            free_submission_only: input.free_submission_only || undefined,
+            activity: serverFiltered ? stripUndefined(activity) : undefined,
             recent_target_days: input.include_recent_changes ? input.recent_target_days : undefined,
             ranking_mode: input.ranking_mode
         }),
@@ -6743,10 +6976,12 @@ async function findHuntTargets(client, config, input) {
         },
         ranking_scope: stripUndefined({
             ...(readObject(programPayload.ranking_scope) ?? {}),
+            local_ranking: serverFiltered ? input.ranking_mode : undefined,
             single_program_catalog_pass: true,
             recent_change_window_days: input.include_recent_changes ? input.recent_target_days : undefined,
             recent_change_page_size: input.include_recent_changes ? input.recent_changes_page_size : undefined
         }),
+        scan: readObject(programPayload.scan),
         result_guidance: {
             final_shortlist: true,
             follow_up_calls_required: false,
@@ -7459,6 +7694,262 @@ function uniqueProgramsFromRepositoryMatches(matches) {
     }
     return [...programs.values()];
 }
+/** Filters the MCP applies to program records after retrieval. */
+function localCatalogFilters(input) {
+    const keys = ["exclude_platforms", "scope_tags", "target_types", "language_tags", "web3", "exclude_web3",
+        "min_bounty_min", "min_bounty_max", "max_bounty_max", "require_bounty", "max_public_report_count",
+        "require_known_report_count", "include_unknown_report_count", "exclude_ctf", "exclude_mobile_only",
+        "exclude_non_web", "has_api_scope", "fresh_launch_days", "min_eligible_targets", "min_total_targets",
+        "min_added_24h", "min_added_7d", "free_submission_only", "competition_risks"].filter(key => {
+        const value = input[key];
+        return Array.isArray(value) ? value.length > 0 : value !== undefined && value !== false;
+    });
+    if (Number(input.min_wildcards) > 0)
+        keys.push("min_wildcards");
+    return keys;
+}
+function legacyCatalogFilters(input) {
+    return input.include_target_samples === true ? [...localCatalogFilters(input), "include_target_samples"] : localCatalogFilters(input);
+}
+function supportsCatalogFilters(client, endpoint) {
+    return client.capabilitySnapshot().status === "negotiated"
+        && readObject(client.endpointCapability(endpoint)?.catalog_filters)?.enabled === true;
+}
+function assertCatalogQuerySupported(client, endpoint, input) {
+    if (!["include", "exclude", "only"].includes(String(input.vdp_mode ?? "exclude"))) {
+        throw new Error("Server-ranked queries accept vdp_mode include, exclude or only. The heuristic only_likely and only_known_no_bounty modes are available only in legacy sampled discovery.");
+    }
+    const capability = client.endpointCapability(endpoint);
+    if (!supportsCatalogFilters(client, endpoint)) {
+        throw new Error("This API deployment does not advertise the required catalog filters. Upgrade the API, or use legacy discovery without server paging or Activity filters.");
+    }
+    if (requiresActivityQuery(input) && readObject(capability?.activity_filters)?.enabled !== true) {
+        throw new Error("Activity catalog filters are unavailable on this API deployment. Ordinary program discovery remains available.");
+    }
+    const kind = input.program_kind ?? (input.contest_like ? "contest" : undefined);
+    if (kind && !readArray(capability?.program_kind_filter).includes(kind)) {
+        throw new Error(`This API deployment does not support program_kind=${String(kind)} on ${endpoint}; the filter was not sent or discarded.`);
+    }
+}
+function hasActivityCatalogInput(input) {
+    return Object.keys(activityCatalogInput).some((key) => key === "sort_by"
+        ? activityCatalogSortSchema.safeParse(input[key]).success
+        : input[key] !== undefined);
+}
+/** Validates and builds one server-ordered catalog query; nothing is sent. */
+function serverCatalogQuery(client, input) {
+    const levels = Array.isArray(input.opportunity_levels) ? input.opportunity_levels : [];
+    if (levels.length > 1)
+        throw new Error("Combined Activity queries accept at most one opportunity tier; separate tier pages cannot form a global ranking.");
+    if (input.sort_by !== undefined && !activityCatalogSortSchema.safeParse(input.sort_by).success) {
+        throw new Error("Combined Activity queries require an enabled server sort_by. Omit it for updated descending; legacy sampled sorts cannot rank these results.");
+    }
+    if (input.contest_like && input.program_kind && input.program_kind !== "contest")
+        throw new Error("contest_like conflicts with program_kind.");
+    const endpoint = levels.length ? "opportunities" : "programs";
+    assertCatalogQuerySupported(client, endpoint, input);
+    assertStableSnapshotSupported(client, endpoint, typeof input.snapshot === "string" ? input.snapshot : undefined);
+    const signals = Object.fromEntries(Object.keys(activityCatalogInput).filter((key) => input[key] !== undefined).map((key) => [key, input[key]]));
+    return {
+        endpoint, level: levels[0], maxPageSize: client.endpointNumber(endpoint, "max_page_size", MAX_PROGRAMS_PER_SEARCH),
+        query: { ...signals, search: input.search, platforms: input.platforms, tags: input.tags,
+            program_kind: input.program_kind ?? (input.contest_like ? "contest" : undefined), updated_since: input.updated_since,
+            vdp_mode: input.vdp_mode, snapshot: input.snapshot }
+    };
+}
+function readServerCatalogPage(client, catalog, page, pageSize, snapshot) {
+    const query = toQuery({ ...catalog.query, snapshot, page, page_size: pageSize });
+    return catalog.level ? client.getOpportunities(catalog.level, query) : client.listPrograms(query);
+}
+async function findServerCatalogPrograms(client, config, input) {
+    // One exact server page: page and snapshot continue it. Local filters use the
+    // ordered scan below instead.
+    const catalog = serverCatalogQuery(client, input);
+    const pageSize = Number(input.max_results) || 10;
+    if (pageSize > catalog.maxPageSize)
+        throw new Error(`Combined Activity pages support max_results up to ${catalog.maxPageSize}; use page and the returned stable snapshot to continue.`);
+    const api = await readServerCatalogPage(client, catalog, Number(input.page ?? 1), pageSize, input.snapshot);
+    const data = readObject(api.data);
+    const mode = input.output_mode === "full" ? "full" : "compact";
+    return withApiMetadata(api, {
+        programs: readArray(data?.programs).map((program) => formatProgram(sanitizeProgram(program, config.webBaseUrl), mode)),
+        ranking_scope: { mode: "server", sort_by: input.sort_by ?? "updated", sort_direction: input.sort_direction ?? "desc" },
+        meta: sanitizeJson(data?.meta)
+    });
+}
+// Pages requested together while scanning. Activity catalog reads share the
+// two-request changes pool, so a wider window would only queue.
+const CATALOG_SCAN_PREFETCH = 2;
+function encodeScanCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor)).toString("base64url");
+}
+function decodeScanCursor(value, fingerprint, pageSize) {
+    let cursor;
+    try {
+        cursor = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    }
+    catch {
+        cursor = undefined;
+    }
+    if (!cursor || cursor.v !== 1 || !Number.isInteger(cursor.p) || cursor.p < 1 || !Number.isInteger(cursor.k) || cursor.k < 0) {
+        throw new Error("Invalid scan cursor. Use scan.next_cursor from the previous find_programs result.");
+    }
+    if (cursor.f !== fingerprint || cursor.s !== pageSize) {
+        throw new Error("This scan cursor belongs to different filters. Repeat the previous filters exactly, or start again without cursor.");
+    }
+    return cursor;
+}
+/**
+ * Reads server-ordered pages and keeps the programs that also pass the local
+ * filters, until enough match or the page/request budget is spent. Filtering
+ * never reorders, so the result is a prefix of the server's global order.
+ */
+async function scanServerCatalog(client, config, input, local, limits) {
+    const catalog = serverCatalogQuery(client, input);
+    const pageSize = catalog.maxPageSize;
+    const localFilters = localCatalogFilters(input);
+    const fingerprint = createHash("sha256")
+        .update(JSON.stringify([catalog.endpoint, catalog.level, toQuery({ ...catalog.query, snapshot: undefined }), localFilters.map((key) => [key, input[key]])]))
+        .digest("base64url").slice(0, 16);
+    const cursorValue = typeof input.cursor === "string" ? input.cursor : undefined;
+    if (cursorValue && input.page !== undefined)
+        throw new Error("Use either cursor or page, not both.");
+    const start = cursorValue ? decodeScanCursor(cursorValue, fingerprint, pageSize)
+        : { v: 1, p: Number(input.page ?? 1), k: 0, s: pageSize, f: fingerprint, a: undefined, t: undefined };
+    const sourceRequests = [];
+    let matches = [];
+    let seen = new Set();
+    let nextPage = start.p;
+    let skip = start.k;
+    let version = start.a;
+    let token = start.t ?? input.snapshot;
+    let totalPages;
+    let serverTotal;
+    let rowsScanned = 0;
+    let pagesRead = 0;
+    let restarted = false;
+    let exhausted = false;
+    let resume;
+    scan: while (matches.length < limits.maxResults) {
+        const pagesLeft = totalPages === undefined ? Number.POSITIVE_INFINITY : totalPages - nextPage + 1;
+        const allowance = Math.min(limits.maxPages - pagesRead, limits.budget.remaining, pagesLeft);
+        if (allowance <= 0)
+            break;
+        // Speculate only from an observed match rate, never before the first page.
+        const rate = rowsScanned > 0 ? Math.max(matches.length / rowsScanned, 0.05) : 1;
+        const needed = pagesRead === 0 ? 1 : Math.ceil((limits.maxResults - matches.length) / (rate * pageSize));
+        const batch = Math.max(1, Math.min(allowance, needed, CATALOG_SCAN_PREFETCH));
+        const pageToken = token;
+        const pages = await Promise.all(Array.from({ length: batch }, (_, index) => nextPage + index)
+            .map(async (page) => ({ page, api: await readServerCatalogPage(client, catalog, page, pageSize, pageToken) })));
+        for (const { page, api } of pages) {
+            pagesRead += 1;
+            limits.budget.remaining -= api.cached || api.coalesced ? 0 : 1;
+            sourceRequests.push({ source: catalog.level ? `opportunities:${catalog.level}` : "programs", page, request_id: api.requestId,
+                upstream_request_id: api.upstreamRequestId, ...apiSourceMetadata(api) });
+            const data = readObject(api.data);
+            const meta = readObject(data?.meta);
+            const pageVersion = stringField(meta ?? {}, "activity_snapshot_id");
+            if (version && pageVersion && pageVersion !== version) {
+                // Never mix rows from two Activity versions. Within one call, restart
+                // once on the new version; a continued scan must be restarted by the caller.
+                if (cursorValue || restarted) {
+                    throw new Error("The Activity version changed while scanning. Rerun the same query without cursor.");
+                }
+                restarted = true;
+                matches = [];
+                seen = new Set();
+                rowsScanned = 0;
+                nextPage = start.p;
+                skip = start.k;
+                totalPages = undefined;
+                version = pageVersion;
+                continue scan;
+            }
+            version ??= pageVersion;
+            totalPages = readNumber(meta?.total_pages) ?? totalPages;
+            serverTotal = readNumber(meta?.total) ?? serverTotal;
+            if (token !== undefined && typeof meta?.snapshot === "string")
+                token = meta.snapshot;
+            const rows = readArray(data?.programs);
+            const lastPage = rows.length < pageSize || (totalPages !== undefined && page >= totalPages);
+            for (let index = skip; index < rows.length; index += 1) {
+                rowsScanned += 1;
+                const candidate = toProgramCandidate(rows[index], config.webBaseUrl);
+                const id = stringField(candidate.program, "id") ?? `${page}:${index}`;
+                if (seen.has(id) || !programCandidateMatches(candidate, local))
+                    continue;
+                seen.add(id);
+                matches.push(candidate);
+                if (matches.length >= limits.maxResults) {
+                    resume = index + 1 < rows.length ? { p: page, k: index + 1 } : lastPage ? undefined : { p: page + 1, k: 0 };
+                    exhausted = resume === undefined;
+                    break scan;
+                }
+            }
+            skip = 0;
+            if (lastPage) {
+                exhausted = true;
+                break scan;
+            }
+            nextPage = page + 1;
+        }
+    }
+    if (!exhausted && !resume)
+        resume = { p: nextPage, k: skip };
+    return {
+        candidates: matches,
+        sourceRequests,
+        scan: stripUndefined({
+            order: "Server order; local filters only remove programs.",
+            sort_by: input.sort_by ?? "updated",
+            sort_direction: input.sort_direction ?? "desc",
+            local_filters: localFilters.length > 0 ? localFilters : undefined,
+            server_matches: serverTotal,
+            rows_scanned: rowsScanned,
+            pages_read: pagesRead,
+            complete: exhausted,
+            next_cursor: resume
+                ? encodeScanCursor({ v: 1, p: resume.p, k: resume.k, s: pageSize, f: fingerprint, a: version, t: typeof token === "string" ? token : undefined })
+                : undefined,
+            activity_snapshot_id: version,
+            restarted_on_new_activity_version: restarted || undefined
+        })
+    };
+}
+/** find_programs with server Activity filters plus local filters or target samples. */
+async function findFilteredServerPrograms(client, config, input, local, maxResults = local.max_results) {
+    const normalized = normalizeFindProgramsInput(local);
+    const warnings = normalized.warnings;
+    local = normalized.input;
+    const budget = { initial: local.upstream_request_budget, remaining: local.upstream_request_budget };
+    const result = await scanServerCatalog(client, config, input, local, { maxResults, maxPages: local.max_pages, budget });
+    if (result.scan.complete !== true) {
+        warnings.push("More server pages remain; scan.next_cursor continues in the same order.");
+    }
+    const samplePrograms = Math.min(local.target_sample_programs, result.candidates.length, Math.max(0, budget.remaining));
+    const targetSamples = local.include_target_samples && samplePrograms > 0
+        ? await collectTargetSamples(client, result.candidates, { ...local, target_sample_programs: samplePrograms }, budget)
+        : {};
+    const outputMode = local.output_mode ?? "compact";
+    return stripUndefined({
+        request_id: randomUUID(),
+        fetched_at: new Date().toISOString(),
+        source_requests: result.sourceRequests,
+        warnings: warnings.length > 0 ? warnings : undefined,
+        upstream_budget: { used: budget.initial - budget.remaining, remaining: budget.remaining },
+        ranking_scope: { mode: "server_filtered", sort_by: result.scan.sort_by, sort_direction: result.scan.sort_direction, complete: result.scan.complete },
+        scan: result.scan,
+        programs: result.candidates.map((candidate, index) => candidateOutput(candidate, index, targetSamples, outputMode)),
+        meta: { returned: result.candidates.length, server_matches: result.scan.server_matches }
+    });
+}
+function programHasNoSubmissionFee(program) {
+    // Mirrors the API: no detected cost, or a detected zero with no maximum.
+    const cost = readObject(program.submission_cost);
+    const amount = numberField(cost, "amount");
+    return amount === undefined || (amount === 0 && (numberField(cost, "maximum_amount") ?? 0) === 0);
+}
 async function findPrograms(client, config, input) {
     const normalized = normalizeFindProgramsInput(input);
     const warnings = normalized.warnings;
@@ -7475,6 +7966,7 @@ async function findPrograms(client, config, input) {
         ...(input.min_wildcards > 0 ? ["wildcard"] : [])
     ]);
     const collected = await collectPrograms(client, {
+        search: input.search,
         platforms: input.platforms,
         tags: upstreamTags,
         program_kind: input.program_kind ?? (input.contest_like ? "contest" : undefined),
@@ -7534,6 +8026,8 @@ async function findPrograms(client, config, input) {
             min_total_targets: input.min_total_targets,
             min_added_24h: input.min_added_24h,
             min_added_7d: input.min_added_7d,
+            free_submission_only: input.free_submission_only || undefined,
+            competition_risks: input.competition_risks?.length ? input.competition_risks : undefined,
             sort_by: input.sort_by,
             output_mode: outputMode
         }),
@@ -8046,7 +8540,7 @@ function programCandidateMatches(candidate, filters) {
         return false;
     }
     const programStatus = normalizeTag(stringField(candidate.program, "program_status") ?? "");
-    if (readBoolean(candidate.program.is_active) === false || programStatus === "paused") {
+    if (!filters.skip_status_check && (readBoolean(candidate.program.is_active) === false || programStatus === "paused")) {
         return false;
     }
     if (filters.platforms.length > 0 && !filters.platforms.map(normalizeTag).includes(normalizeTag(stringField(candidate.program, "platform") ?? ""))) {
@@ -8139,6 +8633,15 @@ function programCandidateMatches(candidate, filters) {
     if (filters.min_added_7d !== undefined && (candidate.added7d ?? 0) < filters.min_added_7d) {
         return false;
     }
+    if (filters.free_submission_only && !programHasNoSubmissionFee(candidate.program)) {
+        return false;
+    }
+    if ((filters.competition_risks?.length ?? 0) > 0) {
+        const risk = normalizeTag(stringField(candidate.program, "competition_risk") ?? "unknown");
+        if (!filters.competition_risks.some((value) => normalizeTag(value) === risk)) {
+            return false;
+        }
+    }
     return true;
 }
 function compareProgramCandidates(left, right, sortBy) {
@@ -8179,6 +8682,8 @@ function compareProgramCandidates(left, right, sortBy) {
         right.lastUpdatedTime - left.lastUpdatedTime);
 }
 function candidateMatchesVdpMode(candidate, vdpMode) {
+    if (vdpMode === "only")
+        return stringField(candidate.program, "program_type") === "vdp";
     if (vdpMode === "exclude") {
         return !candidateLooksLikeVdp(candidate);
     }
@@ -8839,6 +9344,54 @@ function assertProFeature(client, endpoint, flag) {
         throw new Error(`${endpoint} is advertised but ${flag}=false on this API deployment.`);
     }
 }
+function assertActivityTabInputs(tab, args) {
+    const allowed = new Set([...ACTIVITY_SHARED_PARAMS, ...ACTIVITY_TAB_PARAMS[tab]]);
+    const misplaced = Object.entries(args)
+        .filter(([key, value]) => !allowed.has(key) && value !== undefined && value !== false)
+        .map(([key]) => key);
+    if (misplaced.length > 0) {
+        throw new Error(`${misplaced.join(", ")} ${misplaced.length === 1 ? "does" : "do"} not apply to tab=${tab}. Remove ${misplaced.length === 1 ? "it" : "them"} rather than querying a different ranking.`);
+    }
+    if (typeof args.period === "string" && !ACTIVITY_COUNT_TABS.has(tab) && !ACTIVITY_EVENT_PERIODS.includes(args.period)) {
+        throw new Error(`tab=${tab} uses rolling 7d, 30d or 90d periods.`);
+    }
+}
+/** One ranking page without the capabilities document the API repeats on every page. */
+function activityRankingPage(api, includeMap) {
+    const page = proPage(api, "rows");
+    const capabilities = readObject(page.capabilities);
+    delete page.capabilities;
+    // With no enabled default view the API answers sort=null and no rows; keep
+    // only this tab's views so the caller can choose an explicit one.
+    if (page.sort === null && readArray(page.rows).length === 0 && capabilities) {
+        const views = readArray(readArray(capabilities.tabs).map(readObject).find((tab) => tab?.id === page.tab)?.views);
+        page.available_views = views;
+    }
+    return omitMapPoints(page, "points", includeMap);
+}
+function omitMapPoints(payload, field, include) {
+    if (include || !Array.isArray(payload[field]))
+        return payload;
+    const { [field]: points, ...rest } = payload;
+    return { ...rest, map_points_omitted: points.length };
+}
+function assertActivitySnapshotSelector(client, endpoint, snapshot) {
+    // Older deployments ignore unknown parameters silently; never let a binding
+    // the caller relies on be dropped without saying so.
+    if (snapshot === undefined || client.capabilitySnapshot().status !== "negotiated")
+        return;
+    if (client.endpointCapability(endpoint)?.snapshot_parameter !== "snapshot") {
+        throw new Error(`The negotiated BBRadar API does not advertise Activity version binding for ${endpoint}. Omit snapshot or upgrade the API deployment.`);
+    }
+}
+function assertActivityTierFilter(client, tiers) {
+    // An API without the filter answers 422; say why locally and send nothing.
+    if (!Array.isArray(tiers) || tiers.length === 0 || client.capabilitySnapshot().status !== "negotiated")
+        return;
+    if (!Array.isArray(client.endpointCapability("activity_rankings")?.opportunity_tiers)) {
+        throw new Error("The negotiated BBRadar API does not advertise Activity opportunity tier filtering. Omit opportunity_tiers or upgrade the API deployment.");
+    }
+}
 function assertHistoryCapture(client) {
     if (client.capabilitySnapshot().status === "negotiated" &&
         client.endpointCapability("history_changes")?.history_capture_enabled === false) {
@@ -8880,6 +9433,12 @@ function errorPayload(error, decision, toolName, durationMs) {
     };
 }
 function recoveryForGone(error, toolName) {
+    if (toolName === "get_activity_change_detail") {
+        return { action: "refresh_activity_source", message: "Rerun the originating Activity changes or status query without its cursor, keeping its filters. Use the new meta.snapshot_id and event ID for this detail request; do not use snapshot=start." };
+    }
+    if (toolName.startsWith("get_activity_") || toolName === "get_program_payouts") {
+        return { action: "restart_activity_query", message: "Restart this Activity query without its expired cursor or snapshot binding, keeping the same explicit period, basis, precision, sort, direction and filters; call get_activity_snapshot for the current version if binding is needed. Do not combine old pages or pass snapshot=start or after_id." };
+    }
     const detail = typeof error.detail === "string" ? error.detail.toLowerCase() : error.message.toLowerCase();
     if (detail.includes("retained analytics") || detail.includes("precede")) {
         return { action: "choose_supported_interval", message: "Choose dates inside the retained analytics window." };