@bbradar/mcp 0.2.6 → 0.3.1

package/dist/server.js

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { requiresActivityQuery, validateActivityCatalogInput } 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.1";
 const MAX_PROGRAMS_PER_SEARCH = 100;
 const MAX_TARGET_EXPORT = 500;
 const MAX_RECENT_CHANGES = 100;
@@ -45,7 +46,7 @@ const MAX_IN_MEMORY_FEED_CURSORS = 500;
 const MAX_RESOLVE_SEARCH_QUERIES = 4;
 const FAST_RESOLVE_SEARCH_QUERIES = 2;
 const MAX_DIRECT_HANDLE_RESOLUTION_REQUESTS = 96;
-const SDK_VERSION = "1.29.0";
+const SDK_VERSION = "1.31.0";
 const CORE_TOOL_NAMES = new Set([
     "search_programs",
     "get_program",
@@ -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.");
@@ -255,11 +257,11 @@ const stableSnapshotSchema = z
     .string()
     .trim()
     .min(1)
-    .max(1_024)
+    .max(32, "Catalog snapshot tokens have at most 32 characters. Use 'start', then meta.snapshot; Activity snapshot IDs belong only to Activity and payout tools.")
     .refine((value) => !/[\u0000-\u001F\u007F]/.test(value), {
     message: "Snapshot tokens cannot contain control characters."
 })
-    .describe("Optional stable-page token. Send 'start' on page 1, then reuse meta.snapshot with identical filters. Snapshot creation is consistency-first and can be slower; omit it for the fastest live result.");
+    .describe("Optional catalog/feed snapshot token, at most 32 characters. Send 'start' on page 1, then reuse meta.snapshot with identical filters. Do not pass get_activity_snapshot's snapshot_id here. Snapshot creation can be slower; omit it for the fastest live result.");
 const opaqueCursorSchema = z.string().min(1).max(4096).describe("Opaque five-minute cursor. Reuse with identical filters and page size; restart the query on expiry.");
 const analyticsDateSchema = () => z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use an inclusive UTC YYYY-MM-DD date.");
 const proLimitSchema = z.number().int().min(1).max(100);
@@ -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().describe("payout_total requires all_time; payout_increase is a tracked counter increase in 24h/7d/30d/90d; payout_native_90d requires 90d and is provider-reported. Omit to select the period's default metric."),
+    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().describe("Update-event category; requires its own updates_period. scope_period with scope_added_min already filters scope additions and does not need this field."),
+    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 own period. payout_total requires all_time; payout_increase uses 24h/7d/30d/90d; payout_native_90d requires 90d. change_category requires updates_period even when scope_period is present; scope_period with scope_added_min needs no change_category. Use enabled sort_by/sort_direction combinations; default is updated descending. Tracked no_increase/lower require 30d. Catalog snapshot is 'start' or meta.snapshot, never an Activity snapshot_id. An empty result does not authorize relaxing the user's thresholds or restricting platforms to a recent-feed sample.";
+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() {
@@ -415,7 +444,13 @@ function createProfiledToolRegistrar(server, profile, client) {
             const extra = args[args.length - 1];
             return client.withRequestContext(extra.signal, () => callback(...args), readObject(args[0])?.snapshot === "start");
         });
-        const registeredTool = server.registerTool(name, toolConfig, scopedCallback);
+        // Raw SDK shapes otherwise strip unknown arguments. Every advertised
+        // filter must be applied or rejected, including on the older shortcuts.
+        const inputSchema = toolConfig.inputSchema;
+        const strictConfig = inputSchema && !(inputSchema instanceof z.ZodType)
+            ? { ...toolConfig, inputSchema: z.object(inputSchema).strict() }
+            : toolConfig;
+        const registeredTool = server.registerTool(name, strictConfig, scopedCallback);
         const requiredEndpoint = TOOL_ENDPOINT_REQUIREMENTS[name];
         if ((profile === "core" && !CORE_TOOL_NAMES.has(name)) ||
             (requiredEndpoint !== undefined && !client.supportsEndpoint(requiredEndpoint))) {
@@ -432,6 +467,9 @@ 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's snapshot_id binds only Activity capabilities, Activity rankings and program payouts. Catalog/feed tools use snapshot=start then meta.snapshot instead; do not send an Activity snapshot_id to find_programs. Never mix rows from different versions.",
+            "Preserve the user's thresholds, periods and platform scope when discovery times out or returns no matches. A sampled recent-change feed does not enumerate all supported platforms. Inspect partial_success, errors, ranking_scope and scan before claiming complete coverage.",
             "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 +480,9 @@ 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's snapshot_id binds only Activity capabilities, Activity rankings and program payouts. Catalog/feed tools use snapshot=start then meta.snapshot instead; do not send an Activity snapshot_id to find_programs. Never mix rows from different versions.",
+            "Preserve the user's thresholds, periods and platform scope when discovery times out or returns no matches. A sampled recent-change feed does not enumerate all supported platforms. Inspect partial_success, errors, ranking_scope and scan before claiming complete coverage.",
             "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 +519,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. Pass snapshot_id as snapshot only to get_activity_capabilities, get_activity_rankings and get_program_payouts. Catalog/feed tools such as find_programs use snapshot=start then meta.snapshot instead. 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 +724,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 +735,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 () => {
@@ -756,6 +926,7 @@ export function createBbradarServer(client, config) {
             program_id: programIdentifierSchema,
             search: searchTextSchema.optional(),
             target_type: filterValueSchema().optional(),
+            language_tags: languageTagListSchema().describe("Keep targets with any requested language tag. Applied while paging; repeat with the returned next_offset."),
             min_target_score: z.number().int().min(0).max(100).optional(),
             target_opportunity_label: targetOpportunityLabelSchema.optional(),
             competition_risk: competitionRiskSchema.optional(),
@@ -924,8 +1095,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 +1124,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 +1135,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.",
@@ -1027,7 +1204,7 @@ export function createBbradarServer(client, config) {
             include_ineligible: z.boolean().default(false).describe("Include ineligible."),
             recent_changes_page_size: recentChangesPageSizeSchema.default(Math.min(MAX_RECENT_CHANGES, maxTargetChangesPageSize)),
             max_results: z.number().int().min(1).max(MAX_RECENT_CHANGES).default(10),
-            include_full_target_list: z.boolean().default(true).describe("Fetch the newest matching program's complete target list. Set false for the fastest cross-program discovery."),
+            include_full_target_list: z.boolean().default(true).describe("Fetch up to full_target_limit targets for the newest matching program. Check full_targets_has_more and continue with get_program_targets at full_targets_next_offset. Set false for the fastest cross-program discovery."),
             full_target_list_mode: targetListModeSchema.default("identifiers"),
             full_target_limit: z.number().int().min(1).max(MAX_TARGETS_PER_PROGRAM).default(MAX_TARGETS_PER_PROGRAM),
             full_list_include_out_of_scope: z.boolean().default(false),
@@ -1184,16 +1361,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 +1381,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 +1399,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 +1414,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 +1440,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 +1448,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 +2395,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" } },
@@ -2290,6 +2511,7 @@ function bbradarGuide(topic, profile, client) {
         decision_tree: decisionTree.filter((entry) => toolAvailableForContract(client, String(entry.first_tool)) &&
             (topic === "start" || guideEntryMatchesTopic(topic, entry))),
         filters,
+        activity_catalog: activityCatalogGuidance,
         advanced_tools: advancedTools,
         examples
     };
@@ -2322,6 +2544,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" } },
@@ -2365,7 +2590,8 @@ function coreBbradarGuide(topic, client) {
         ],
         decision_tree: decisionTree.filter((entry) => toolAvailableForContract(client, String(entry.first_tool)) &&
             (topic === "start" || guideEntryMatchesTopic(topic, entry))),
-        available_tools: [...CORE_TOOL_NAMES].filter((name) => toolAvailableForContract(client, name))
+        available_tools: [...CORE_TOOL_NAMES].filter((name) => toolAvailableForContract(client, name)),
+        activity_catalog: activityCatalogGuidance
     };
 }
 function toolAvailableForContract(client, toolName) {
@@ -3375,29 +3601,14 @@ async function runResolvedProgramAction(client, config, programId, input) {
         });
     }
     if (input.action === "targets") {
-        const api = await client.getProgramTargets(programId);
-        const data = readObject(api.data);
-        const rawTargets = readArray(data?.targets);
-        const sanitizedTargets = rawTargets
-            .map(sanitizeTarget)
-            .filter((target) => targetHasAllowedScope(target, {
+        return getProgramTargetsPayload(client, {
+            target_type: input.target_type,
+            language_tags: input.language_tags,
             include_out_of_scope: input.include_out_of_scope,
             include_ineligible: input.include_ineligible,
-            strict_scope_filter: true
-        }));
-        const targets = sanitizedTargets.slice(0, input.max_targets);
-        return withApiMetadata(api, {
-            program_id: programId,
-            targets: formatTargetList(targets, input.target_list_mode),
-            meta: {
-                limit: input.max_targets,
-                output_mode: input.target_list_mode,
-                total_active_targets: rawTargets.length,
-                total_after_filters: sanitizedTargets.length,
-                returned: targets.length,
-                has_more: sanitizedTargets.length > targets.length
-            }
-        });
+            strict_scope_filter: true,
+            offset: 0, limit: input.max_targets, output_mode: input.target_list_mode
+        }, programId);
     }
     return checkProgramNewTargets(client, config, {
         program_id: programId,
@@ -4523,30 +4734,18 @@ async function getLatestAddedTargets(client, config, input) {
         .map((change) => readObject(change.target))
         .filter((target) => target !== undefined);
     let fullTargets = [];
-    let totalActiveTargets;
-    let totalAfterFilters;
+    let fullTargetsMeta;
     if (input.include_full_target_list && programId) {
-        const targetsApi = await client.getProgramTargets(programId);
-        const targetsData = readObject(targetsApi.data);
-        const rawTargets = readArray(targetsData?.targets);
-        fullTargets = rawTargets
-            .map(sanitizeTarget)
-            .filter((target) => targetHasAllowedScope(target, {
+        const payload = await getProgramTargetsPayload(client, {
             include_out_of_scope: input.full_list_include_out_of_scope,
             include_ineligible: input.full_list_include_ineligible,
-            strict_scope_filter: false
-        }));
-        totalActiveTargets = rawTargets.length;
-        totalAfterFilters = fullTargets.length;
-        sourceRequests.push({
-            source: "program_targets",
-            program_id: programId,
-            request_id: targetsApi.requestId,
-            upstream_request_id: targetsApi.upstreamRequestId,
-            ...apiSourceMetadata(targetsApi)
-        });
+            strict_scope_filter: false,
+            offset: 0, limit: input.full_target_limit, output_mode: input.full_target_list_mode
+        }, programId);
+        fullTargets = readArray(payload.targets);
+        fullTargetsMeta = readObject(payload.meta);
+        sourceRequests.push(...readArray(payload.source_requests).map(readObject).filter((request) => request !== undefined));
     }
-    const limitedFullTargets = fullTargets.slice(0, input.full_target_limit);
     return stripUndefined({
         request_id: randomUUID(),
         source_requests: sourceRequests,
@@ -4555,17 +4754,19 @@ async function getLatestAddedTargets(client, config, input) {
         program,
         matches,
         new_targets: formatTargetList(latestNewTargets, input.full_target_list_mode),
-        full_targets: input.include_full_target_list ? formatTargetList(limitedFullTargets, input.full_target_list_mode) : undefined,
+        full_targets: input.include_full_target_list ? fullTargets : undefined,
         meta: stripUndefined({
             recent_changes_scanned: changes.length,
             matching_changes_scanned: matchingChanges.length,
             matches_returned: matches.length,
             matches_has_more: matches.length < matchingChanges.length,
             new_targets_returned: formatTargetList(latestNewTargets, input.full_target_list_mode).length,
-            full_targets_total_active: totalActiveTargets,
-            full_targets_total_after_filters: totalAfterFilters,
-            full_targets_returned: input.include_full_target_list ? formatTargetList(limitedFullTargets, input.full_target_list_mode).length : undefined,
-            full_targets_has_more: input.include_full_target_list ? limitedFullTargets.length < fullTargets.length : undefined
+            full_targets_total_active: fullTargetsMeta?.total_active_targets,
+            full_targets_total_after_filters: fullTargetsMeta?.total_after_filters,
+            full_targets_returned: input.include_full_target_list ? fullTargets.length : undefined,
+            full_targets_has_more: fullTargetsMeta?.has_more,
+            full_targets_next_offset: fullTargetsMeta?.next_offset,
+            full_targets_possibly_incomplete: fullTargetsMeta?.possibly_incomplete
         })
     });
 }
@@ -4603,15 +4804,21 @@ function latestAddedProgramMatches(change, input, platformFilters) {
     return true;
 }
 async function getProgramTargetsPayload(client, input, programId) {
-    const pageSize = client.endpointNumber("program_targets", "max_page_size", MAX_TARGETS_PER_PROGRAM);
+    const maxPageSize = client.endpointNumber("program_targets", "max_page_size", MAX_TARGETS_PER_PROGRAM);
     // `eligibility=eligible` is an API-level in-scope bounty-eligibility filter,
     // so the common eligible-only path needs no second local scope pass.
-    const directOffsetPaging = !input.include_ineligible || (!input.strict_scope_filter && input.include_out_of_scope);
+    const languageTags = new Set((input.language_tags ?? []).map(normalizeTag));
+    const directOffsetPaging = languageTags.size === 0 && (!input.include_ineligible || (!input.strict_scope_filter && input.include_out_of_scope));
+    // Bound direct reads to the requested prefix. Local post-filters still need
+    // full pages to find sparse matches. Offsets remain filtered row offsets,
+    // independent of the page size used by an earlier call.
+    const pageSize = directOffsetPaging ? Math.min(maxPageSize, input.offset + input.limit) : maxPageSize;
     const collected = [];
     let matchedSeen = directOffsetPaging ? Math.floor(input.offset / pageSize) * pageSize : 0;
     let page = directOffsetPaging ? Math.floor(input.offset / pageSize) + 1 : 1;
     const firstPage = page;
     let api;
+    const sourceRequests = [];
     let upstreamMeta;
     let upstreamHasMore = false;
     do {
@@ -4625,11 +4832,15 @@ async function getProgramTargetsPayload(client, input, programId) {
             page,
             page_size: pageSize
         });
+        sourceRequests.push({ source: "program_targets", program_id: programId, page,
+            request_id: api.requestId, upstream_request_id: api.upstreamRequestId, ...apiSourceMetadata(api) });
         const data = readObject(api.data);
         upstreamMeta = readObject(data?.meta);
         for (const target of readArray(data?.targets).map(sanitizeTarget)) {
             if (!targetHasAllowedScope(target, input))
                 continue;
+            if (languageTags.size > 0 && !arraysIntersectNormalized(languageTags, readStringArrayField(target, "language_tags")))
+                continue;
             if (matchedSeen >= input.offset && collected.length < input.limit)
                 collected.push(target);
             matchedSeen += 1;
@@ -4647,8 +4858,10 @@ async function getProgramTargetsPayload(client, input, programId) {
         throw new Error("No program target response was collected.");
     }
     const targets = collected;
+    const hasMore = upstreamHasMore || matchedSeen > input.offset + targets.length;
     return withApiMetadata(api, {
         program_id: programId,
+        source_requests: sourceRequests,
         targets: formatTargetList(targets, input.output_mode),
         meta: {
             offset: input.offset,
@@ -4657,7 +4870,8 @@ async function getProgramTargetsPayload(client, input, programId) {
             total_active_targets: readNumber(upstreamMeta?.total) ?? matchedSeen,
             total_after_filters: upstreamHasMore ? undefined : matchedSeen,
             returned: targets.length,
-            has_more: upstreamHasMore || matchedSeen > input.offset + targets.length,
+            has_more: hasMore,
+            next_offset: hasMore ? input.offset + targets.length : undefined,
             upstream_has_more: upstreamHasMore,
             possibly_incomplete: upstreamHasMore,
             upstream_pages_fetched: page - firstPage,
@@ -4670,9 +4884,16 @@ async function getProgramTargetsPayload(client, input, programId) {
     });
 }
 async function getProgramTargetsExportFallbackPayload(client, input, programId) {
+    if (input.search || input.target_type || input.min_target_score !== undefined
+        || input.target_opportunity_label || input.competition_risk) {
+        throw new Error("The per-program targets endpoint is unavailable. Its search, type and intelligence filters cannot be preserved by the export fallback; the requested filters were not discarded.");
+    }
     const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, programId);
-    const sanitizedTargets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, input));
+    const languageTags = new Set((input.language_tags ?? []).map(normalizeTag));
+    const sanitizedTargets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, input)
+        && (languageTags.size === 0 || arraysIntersectNormalized(languageTags, readStringArrayField(target, "language_tags"))));
     const targets = sanitizedTargets.slice(input.offset, input.offset + input.limit);
+    const hasMore = input.offset + targets.length < sanitizedTargets.length;
     return stripUndefined({
         request_id: exportLookup.requestId,
         upstream_request_id: exportLookup.upstreamRequestId,
@@ -4686,10 +4907,10 @@ async function getProgramTargetsExportFallbackPayload(client, input, programId)
             offset: input.offset,
             limit: input.limit,
             output_mode: input.output_mode,
-            total_active_targets: exportLookup.rawTargets.length,
-            total_after_filters: sanitizedTargets.length,
+            ...fallbackTargetCoverage(exportLookup, sanitizedTargets.length),
             returned: targets.length,
-            has_more: input.offset + input.limit < sanitizedTargets.length,
+            has_more: hasMore || exportLookup.coverage?.possibly_incomplete === true,
+            next_offset: hasMore ? input.offset + targets.length : undefined,
             target_source: exportLookup.source,
             target_list_unavailable: exportLookup.unavailable,
             fallback_error: exportLookup.error
@@ -4718,6 +4939,7 @@ async function fetchProgramTargetsWithEndpointFallback(client, programId) {
             })),
             source: "program_targets",
             rawTargets,
+            coverage: targetPageCoverage(data, rawTargets.length, rawTargets.length),
             sourceRequests: [
                 {
                     source: "program_targets",
@@ -4817,14 +5039,21 @@ function cacheTtlMsFromDiagnostics(cache) {
 }
 async function fetchProgramTargetsFromExportFallback(client, programId) {
     try {
+        const limit = Math.min(MAX_TARGET_EXPORT, client.endpointNumber("target_export", "max_targets", MAX_TARGET_EXPORT));
         const api = await client.exportTargets({
             program_ids: [programId],
             include_out_of_scope: true,
             include_ineligible: true,
             format: "json",
-            limit: MAX_TARGET_EXPORT
+            limit
         });
         const rawTargets = readExportTargetRows(api.data).map((row) => sanitizeTarget(readObject(row)?.target ?? row));
+        const data = readObject(api.data);
+        const coverage = targetPageCoverage({ meta: {
+                ...readObject(data?.meta),
+                // A full capped export is not proof that the inventory ends here.
+                has_more: readObject(data?.meta)?.has_more === true || rawTargets.length >= limit
+            } }, rawTargets.length, rawTargets.length);
         return {
             requestId: api.requestId,
             upstreamRequestId: api.upstreamRequestId,
@@ -4838,6 +5067,7 @@ async function fetchProgramTargetsFromExportFallback(client, programId) {
             })),
             source: "target_export",
             rawTargets,
+            coverage,
             sourceRequests: [
                 {
                     source: "target_export",
@@ -5098,8 +5328,7 @@ async function getProgramScopeSummary(client, config, input) {
         program: formatProgram(lookup.program, "compact"),
         scope: buildTargetScopeSummary(targets, input.target_list_mode, input.group_limit, input.include_out_of_scope, input.include_ineligible),
         meta: {
-            total_active_targets: rawTargets.length,
-            total_after_filters: targets.length,
+            ...targetPageCoverage(targetsData, rawTargets.length, targets.length),
             target_list_mode: input.target_list_mode,
             group_limit: input.group_limit,
             target_source: "program_targets",
@@ -5124,8 +5353,7 @@ async function getProgramScopeSummaryFromIndexFallback(client, indexFallback, in
         program: formatProgram(indexFallback.program, "compact"),
         scope: buildTargetScopeSummary(targets, input.target_list_mode, input.group_limit, input.include_out_of_scope, input.include_ineligible),
         meta: stripUndefined({
-            total_active_targets: exportLookup.rawTargets.length,
-            total_after_filters: targets.length,
+            ...fallbackTargetCoverage(exportLookup, targets.length),
             target_list_mode: input.target_list_mode,
             group_limit: input.group_limit,
             target_source: exportLookup.source,
@@ -5161,8 +5389,7 @@ async function getProgramTargetBreakdown(client, config, input) {
             groups: readObject(scope.groups)
         },
         meta: {
-            total_active_targets: rawTargets.length,
-            total_after_filters: targets.length,
+            ...targetPageCoverage(targetsData, rawTargets.length, targets.length),
             target_list_mode: input.target_list_mode,
             group_limit: input.group_limit,
             target_source: "program_targets",
@@ -5170,6 +5397,32 @@ async function getProgramTargetBreakdown(client, config, input) {
         }
     });
 }
+function targetPageCoverage(data, rows, filteredRows) {
+    const meta = readObject(data?.meta);
+    const total = numberField(meta, "total");
+    const incomplete = meta?.has_more === true || (numberField(meta, "total_pages") ?? 1) > 1
+        || (total !== undefined && total > rows);
+    return stripUndefined({
+        total_active_targets: total ?? (incomplete ? undefined : rows),
+        total_after_filters: incomplete ? undefined : filteredRows,
+        targets_scanned: rows,
+        matching_targets_scanned: filteredRows,
+        possibly_incomplete: incomplete,
+        count_scope: incomplete ? "sampled_target_page" : "complete_target_inventory"
+    });
+}
+function fallbackTargetCoverage(lookup, filteredRows) {
+    const incomplete = lookup.unavailable || lookup.coverage?.possibly_incomplete === true;
+    return stripUndefined({
+        ...lookup.coverage,
+        total_active_targets: lookup.unavailable ? undefined : lookup.coverage?.total_active_targets ?? (incomplete ? undefined : lookup.rawTargets.length),
+        total_after_filters: incomplete ? undefined : filteredRows,
+        targets_scanned: lookup.rawTargets.length,
+        matching_targets_scanned: filteredRows,
+        possibly_incomplete: incomplete,
+        count_scope: lookup.unavailable ? "unavailable" : incomplete ? "sampled_target_page" : "complete_target_inventory"
+    });
+}
 async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback, input) {
     const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, input.program_id);
     const targets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, {
@@ -5196,8 +5449,7 @@ async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback,
             groups: readObject(scope.groups)
         },
         meta: stripUndefined({
-            total_active_targets: exportLookup.rawTargets.length,
-            total_after_filters: targets.length,
+            ...fallbackTargetCoverage(exportLookup, targets.length),
             target_list_mode: input.target_list_mode,
             group_limit: input.group_limit,
             target_source: exportLookup.source,
@@ -6040,6 +6292,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 +6853,22 @@ 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 huntStartedAt = Date.now();
+    const phaseTiming = {};
+    const runStage = async (phase, timeoutMs, callback) => {
+        const startedAt = Date.now();
+        try {
+            return await client.withRequestTimeout(timeoutMs, callback);
+        }
+        finally {
+            phaseTiming[phase] = Date.now() - startedAt;
+        }
+    };
+    validateActivityCatalogInput(activity);
     const warnings = [];
     const errors = [];
     const selfHostedOnly = isSelfHostedOnlyPlatformSelection(input.platforms);
@@ -6641,6 +6911,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,14 +6933,29 @@ 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);
+    // Catalog discovery and optional changes share at most 60% of the tool
+    // deadline. Keep at least 30% for exact targets and 10% for the response.
     const [programPayload, recentResult] = await Promise.all([
-        findPrograms(client, config, programInput),
+        runStage("program_discovery_ms", Math.floor(config.requestTimeoutMs * 0.6), () => 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, true)
+            : findPrograms(client, config, programInput, {
+                allowPartialTimeout: true, excludeVdpUpstream: true
+            })),
         recentChangesEnabled
-            ? fetchHuntRecentChanges(client, config, input, recentChangeQueries)
+            ? runStage("recent_changes_ms", Math.floor(config.requestTimeoutMs * 0.3), () => fetchHuntRecentChanges(client, config, input, recentChangeQueries))
             : Promise.resolve({ changes: [], sourceRequests: [], requestsUsed: 0, errors: [] })
     ]);
+    client.throwIfRequestAborted();
     const programWarnings = readArray(programPayload.warnings).filter((warning) => typeof warning === "string");
     warnings.push(...programWarnings);
+    errors.push(...readArray(programPayload.errors).map(readObject).filter((error) => error !== undefined));
     errors.push(...recentResult.errors);
     const programBudget = readObject(programPayload.upstream_budget);
     const programRequestsUsed = readNumber(programBudget?.used) ?? 0;
@@ -6688,8 +6974,12 @@ async function findHuntTargets(client, config, input) {
     const finalistEntries = preliminaryRankedEntries
         .slice(0, sampledProgramCount)
         .map((entry) => entry.entry);
-    const targetResult = await collectHuntTargetSamples(client, finalistEntries, input);
+    const targetResult = await runStage("target_sampling_ms", Math.floor(config.requestTimeoutMs * 0.9) - (Date.now() - huntStartedAt), () => collectHuntTargetSamples(client, finalistEntries, input));
+    client.throwIfRequestAborted();
     errors.push(...targetResult.errors);
+    if (errors.length > 0) {
+        warnings.push("Some discovery or enrichment reads failed or reached their time budget. Returned matches preserve the requested filters; missing target samples or change evidence are unavailable, not confirmed absent. Report the incomplete coverage without narrowing platforms or relaxing thresholds.");
+    }
     if (sampledProgramCount < Math.min(input.max_results, programEntries.length)) {
         warnings.push(`The upstream request budget limited the final exact target shortlist to ${sampledProgramCount} of ${Math.min(input.max_results, programEntries.length)} requested results.`);
     }
@@ -6703,6 +6993,10 @@ async function findHuntTargets(client, config, input) {
     }));
     const targetRequestsUsed = targetResult.requestsUsed;
     const totalRequestsUsed = programRequestsUsed + recentResult.requestsUsed + targetRequestsUsed;
+    const coverageIncomplete = errors.length > 0
+        || readObject(programPayload.ranking_scope)?.possibly_incomplete === true
+        || readObject(programPayload.scan)?.complete === false
+        || sampledProgramCount < Math.min(input.max_results, programEntries.length);
     return stripUndefined({
         request_id: randomUUID(),
         fetched_at: new Date().toISOString(),
@@ -6733,6 +7027,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,14 +7039,19 @@ 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,
-            instruction: "Use these matches as the final shortlist. Exact bounded target samples and recent additions are already included; call get_program_targets only if the user explicitly requests an exhaustive scope dump for one selected program."
+            coverage_incomplete: coverageIncomplete,
+            instruction: coverageIncomplete
+                ? "Use the bounded matches and report warnings and incomplete coverage. Preserve the user's periods, thresholds and platform scope; do not infer supported platforms from a sampled recent-change feed."
+                : "Use these matches as the final shortlist. Exact bounded target samples and recent additions are already included; call get_program_targets only if the user explicitly requests an exhaustive scope dump for one selected program."
         },
         matches,
         meta: {
@@ -6763,7 +7064,8 @@ async function findHuntTargets(client, config, input) {
             model_round_trips_expected: 1,
             parallel_recent_change_fetch: recentChangeQueries.length > 0,
             bulk_resource_links_suppressed: true,
-            partial_success: errors.length > 0
+            partial_success: errors.length > 0,
+            phase_timing: phaseTiming
         }
     });
 }
@@ -7459,10 +7761,288 @@ function uniqueProgramsFromRepositoryMatches(matches) {
     }
     return [...programs.values()];
 }
-async function findPrograms(client, config, input) {
+/** 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) {
+    validateActivityCatalogInput(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 = [];
+    const errors = [];
+    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 batchStart = nextPage;
+        const pages = await Promise.allSettled(Array.from({ length: batch }, (_, index) => batchStart + index)
+            .map(async (page) => ({ page, api: await readServerCatalogPage(client, catalog, page, pageSize, pageToken) })));
+        // Count all admitted reads, including a failed page or a prefetched page
+        // beyond a gap; only the contiguous successful prefix enters the ranking.
+        for (const result of pages) {
+            const noRequest = result.status === "fulfilled" ? result.value.api.cached || result.value.api.coalesced
+                : result.reason instanceof BBRadarApiError && (result.reason.cached || result.reason.coalesced);
+            limits.budget.remaining -= noRequest ? 0 : 1;
+        }
+        for (const [index, result] of pages.entries()) {
+            if (result.status === "rejected") {
+                if (!limits.allowPartialTimeout || pagesRead === 0 || !(result.reason instanceof BBRadarApiError) || result.reason.status !== 408)
+                    throw result.reason;
+                errors.push(apiOperationError(`program catalog page ${batchStart + index}`, result.reason));
+                break scan;
+            }
+            const { page, api } = result.value;
+            pagesRead += 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,
+        errors,
+        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,
+            deadline_reached: errors.length > 0 || undefined
+        })
+    };
+}
+/** find_programs with server Activity filters plus local filters or target samples. */
+async function findFilteredServerPrograms(client, config, input, local, maxResults = local.max_results, allowPartialTimeout = false) {
+    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, allowPartialTimeout });
+    if (result.errors.length > 0)
+        warnings.push("Program discovery reached its time budget; ranking covers only the completed server-ordered prefix.");
+    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,
+        errors: result.errors.length > 0 ? result.errors : undefined,
+        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, execution = {}) {
     const normalized = normalizeFindProgramsInput(input);
     const warnings = normalized.warnings;
     input = normalized.input;
+    const errors = [];
     const budget = {
         initial: input.upstream_request_budget,
         remaining: input.upstream_request_budget
@@ -7475,14 +8055,17 @@ 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),
+        vdp_mode: execution.excludeVdpUpstream && input.vdp_mode === "exclude" ? "exclude" : undefined,
         updated_since: input.updated_since,
         opportunity_levels: input.opportunity_levels,
         max_pages: input.max_pages,
         budget,
-        warnings
+        warnings,
+        partialTimeoutErrors: execution.allowPartialTimeout ? errors : undefined
     });
     const filteredCandidates = collected.programs
         .map((program) => toProgramCandidate(program, config.webBaseUrl))
@@ -7506,6 +8089,7 @@ async function findPrograms(client, config, input) {
         source_requests: collected.sourceRequests,
         fetched_at: new Date().toISOString(),
         warnings: warnings.length > 0 ? warnings : undefined,
+        errors: errors.length > 0 ? errors : undefined,
         filters: stripUndefined({
             platforms: input.platforms.length > 0 ? input.platforms : undefined,
             exclude_platforms: input.exclude_platforms && input.exclude_platforms.length > 0 ? input.exclude_platforms : undefined,
@@ -7534,6 +8118,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
         }),
@@ -7546,7 +8132,7 @@ async function findPrograms(client, config, input) {
             platform_filter: input.platforms.length > 0 ? input.platforms : "all_platforms",
             max_pages_scanned_per_source: input.max_pages,
             upstream_total_pages: collected.totalPagesBySource,
-            possibly_incomplete: isRankingPossiblyIncomplete(collected.totalPagesBySource, input.max_pages)
+            possibly_incomplete: errors.length > 0 || isRankingPossiblyIncomplete(collected.totalPagesBySource, input.max_pages)
         },
         programs,
         meta: {
@@ -7951,20 +8537,39 @@ async function collectProgramSource(client, source, sourceIndex, options) {
 async function fetchProgramPage(client, source, sourceIndex, page, options) {
     const runWithSlot = options.runWithProgramPageSlot ?? runImmediately;
     return runWithSlot(async () => {
+        const endpoint = source.kind === "programs" ? "programs" : "opportunities";
+        const vdpModes = readArray(readObject(client.endpointCapability(endpoint)?.catalog_filters)?.vdp_mode);
         const query = toQuery({
             search: options.search,
             platforms: options.platforms,
             tags: options.tags,
             updated_since: options.updated_since,
             program_kind: source.kind === "programs" ? options.program_kind : undefined,
+            // This removes only known VDPs; unknown classifications with positive
+            // rewards still reach the local filters. Older APIs keep local exclusion.
+            vdp_mode: supportsCatalogFilters(client, endpoint) && vdpModes.includes("exclude") ? options.vdp_mode : undefined,
             page,
-            page_size: MAX_PROGRAMS_PER_SEARCH
+            page_size: Math.min(MAX_PROGRAMS_PER_SEARCH, client.endpointNumber(endpoint, "max_page_size", MAX_PROGRAMS_PER_SEARCH))
         });
         if (!tryConsumeBudget(options.budget)) {
             addUniqueWarning(options.warnings, "Upstream request budget was exhausted before all requested program pages could be fetched.");
             return undefined;
         }
-        const api = source.kind === "opportunity" ? await client.getOpportunities(source.level, query) : await client.listPrograms(query);
+        let api;
+        try {
+            api = source.kind === "opportunity" ? await client.getOpportunities(source.level, query) : await client.listPrograms(query);
+        }
+        catch (error) {
+            // Hunts can retain completed catalog pages. Ordinary discovery keeps its
+            // existing failure contract, and a failed first page is never an empty hit.
+            if (page === 1 || !options.partialTimeoutErrors || !(error instanceof BBRadarApiError) || error.status !== 408)
+                throw error;
+            if (error.cached || error.coalesced)
+                options.budget.remaining += 1;
+            options.partialTimeoutErrors.push(apiOperationError(`program catalog page ${page}`, error));
+            addUniqueWarning(options.warnings, "Program discovery reached its time budget; ranking covers only completed catalog pages.");
+            return undefined;
+        }
         refundBudgetIfNoUpstreamRequest(options.budget, api);
         const data = readObject(api.data);
         const meta = readObject(data?.meta);
@@ -8046,7 +8651,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 +8744,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 +8793,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);
     }
@@ -8775,6 +9391,7 @@ function compactToolText(payload, isError) {
         }));
     }
     const meta = readObject(payload.meta);
+    const coverageIncomplete = readObject(payload.result_guidance)?.coverage_incomplete === true;
     const returned = numberField(meta, "returned") ??
         [
             readArray(payload.programs).length,
@@ -8786,6 +9403,12 @@ function compactToolText(payload, isError) {
         request_id: payload.request_id,
         summary: "Full tool result is available in structuredContent.",
         returned,
+        partial_success: meta?.partial_success === true ? true : undefined,
+        coverage_incomplete: coverageIncomplete ? true : undefined,
+        errors: meta?.partial_success === true ? readArray(payload.errors).map((error) => {
+            const value = readObject(error);
+            return stripUndefined({ operation: value?.operation, status: value?.status });
+        }) : undefined,
         mcp_timing: payload.mcp_timing
     }));
 }
@@ -8839,6 +9462,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 +9551,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." };