@bbradar/mcp 0.2.2 → 0.2.3

package/dist/server.js

@@ -6,7 +6,7 @@ import { NumericCursorStore } from "./cursorStore.js";
 import { stableStringify, stripUndefined } from "./json.js";
 import { FixedWindowRateLimiter } from "./rateLimit.js";
 import { readArray, readBoolean, readNumber, readObject, readString, sanitizeJson, sanitizeChange, sanitizeProgram, sanitizeRepositoryChange, sanitizeTarget, sanitizeTargetsForExport } from "./sanitize.js";
-const SERVER_VERSION = "0.2.2";
+const SERVER_VERSION = "0.2.3";
 const MAX_PROGRAMS_PER_SEARCH = 100;
 const MAX_TARGET_EXPORT = 500;
 const MAX_RECENT_CHANGES = 100;
@@ -21,6 +21,10 @@ const MAX_FIND_TARGET_SAMPLE_PROGRAMS = 10;
 const MAX_FIND_TARGET_SAMPLES = 20;
 const MAX_FIND_UPSTREAM_REQUEST_BUDGET = 50;
 const DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET = 20;
+const DEFAULT_HUNT_PROGRAM_PAGES = 7;
+const MAX_HUNT_RESULTS = 15;
+const MAX_HUNT_TARGETS_PER_RESULT = 10;
+const MAX_BULK_PROGRAM_RESOURCE_LINKS = 5;
 const DEFAULT_RESOLVE_UPSTREAM_REQUEST_BUDGET = 12;
 const MAX_ACCEPTED_NUMERIC_LIMIT = 1_000;
 const PROGRAM_COLLECTION_CONCURRENCY = 4;
@@ -50,6 +54,7 @@ const CORE_TOOL_NAMES = new Set([
     "get_program_targets",
     "get_recent_changes",
     "get_repository_changes",
+    "find_hunt_targets",
     "find_repository_hunt_targets",
     "get_latest_added_targets",
     "get_opportunities",
@@ -397,14 +402,16 @@ export function createBbradarServer(client, config) {
             "Use BBRadar only for passive bug bounty intelligence; never scan or contact targets.",
             "This server uses the compact core tool profile. Start with get_bbradar_guide when unsure.",
             "Use resolve_program or run_program_name_action for a named program.",
-            "Use find_programs for general discovery and find_programs_by_target for reverse target lookup.",
+            "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.",
             "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."
         ]
         : [
             "Use BBRadar only for passive bug bounty intelligence; never scan or contact targets.",
             "When unsure which BBRadar tool to use, call get_bbradar_guide first. It is local-only and cheap.",
-            "Simple default path: find_program_candidates for discovery, run_program_name_action for one named program, get_program_eligible_targets_by_name for target lists by program name.",
+            "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.",
             "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.",
@@ -412,7 +419,7 @@ export function createBbradarServer(client, config) {
             "Self-Hosted programs use Self-Hosted:slug ids and are available through program search, exact detail, and target tools. Respect data_capabilities; do not infer missing opportunity, report-count, target-change, submission-cost, or repository signals.",
             "Freshness: find_recently_updated_programs, get_latest_added_targets, check_program_new_targets, check_watchlist_new_targets, find_recent_by_type, get_program_scope_delta.",
             "Repository activity: get_repository_changes defaults to compact program-only events. Seed with after_id, then resume the in-memory per-filter cursor.",
-            "Discovery: find_program_candidates, find_wildcard_programs, find_recently_added_wildcards, find_low_competition_high_reward, find_stack_matches, find_language_programs, find_target_type_programs, find_reward_programs, find_paid_programs, find_vdp_programs, find_web3_contests, find_low_noise_programs.",
+            "Discovery: find_hunt_targets is the one-call default; find_program_candidates, find_wildcard_programs, find_recently_added_wildcards, find_low_competition_high_reward, find_stack_matches, find_language_programs, find_target_type_programs, find_reward_programs, find_paid_programs, find_vdp_programs, find_web3_contests, and find_low_noise_programs are lower-level alternatives.",
             "Details: get_program_brief, get_program_scope_summary, get_program_target_breakdown, find_programs_by_target, compare_programs_compact.",
             "Prefer compact/identifier outputs and disclose sampled ranking scope when present."
         ];
@@ -741,6 +748,51 @@ export function createBbradarServer(client, config) {
             source_requests: collected.sourceRequests.length > 1 ? collected.sourceRequests : undefined
         }), "repository_changes", "repository changes", continuationStore, 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. Use find_repository_hunt_targets instead only when Git or repository activity is explicitly requested.",
+        inputSchema: {
+            platforms: platformListSchema(),
+            exclude_platforms: stringListSchema("Platforms to exclude from the final shortlist."),
+            tags: tagListSchema(),
+            scope_tags: scopeTagListSchema(),
+            target_types: targetTypeListSchema(),
+            language_tags: languageTagListSchema(),
+            surface_mode: z.enum(["any", "web2", "web3"]).default("any"),
+            min_bounty_max: z.number().int().min(0).optional(),
+            require_bounty: z.boolean().default(true),
+            max_public_report_count: z.number().int().min(0).optional(),
+            include_unknown_report_count: z.boolean().default(true),
+            min_eligible_targets: z.number().int().min(0).default(3),
+            min_total_targets: z.number().int().min(0).optional(),
+            min_wildcards: z.number().int().min(0).max(1000).default(0),
+            min_added_7d: z.number().int().min(0).optional(),
+            fresh_launch_days: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).optional(),
+            updated_since: isoDateTimeSchema.optional(),
+            min_target_score: z.number().int().min(0).max(100).optional(),
+            target_opportunity_label: targetOpportunityLabelSchema.optional(),
+            competition_risk: competitionRiskSchema.optional(),
+            include_recent_changes: z.boolean().default(true),
+            recent_target_days: z.number().int().min(1).max(365).default(30),
+            recent_changes_page_size: recentChangesPageSizeSchema.default(Math.min(MAX_RECENT_CHANGES, maxTargetChangesPageSize)),
+            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),
+            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)
+        },
+        outputSchema: {
+            ...apiEnvelopeOutputShape(),
+            matches: z.array(jsonRecordSchema()).optional(),
+            filters: jsonRecordSchema().optional(),
+            errors: z.array(jsonRecordSchema()).optional(),
+            upstream_budget: jsonRecordSchema().optional(),
+            ranking_scope: jsonRecordSchema().optional(),
+            result_guidance: jsonRecordSchema().optional(),
+            meta: jsonRecordSchema().optional()
+        },
+        annotations: readOnlyAnnotations
+    }, (args) => runTool("find_hunt_targets", config, rateLimiter, async () => findHuntTargets(client, config, args)));
     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 platforms, Web2/Web3 modes, reward thresholds, target types, languages, and freshness criteria.",
@@ -989,7 +1041,7 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("find_programs", {
         title: "Find BBRadar Programs",
-        description: "Ranked program discovery with positive and negative platform/surface filters and compact output. Strict-filter retries reuse cached upstream pages, so relax one local filter at a time when a narrow query returns no candidates.",
+        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: {
             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."),
@@ -1881,10 +1933,10 @@ function bbradarGuide(topic, profile, client) {
     }
     const primaryEntryPoints = [
         {
-            tool: "find_program_candidates",
-            use_when: "The user wants good programs to hunt, broad discovery, or does not name one exact program.",
+            tool: "find_hunt_targets",
+            use_when: "The user wants good targets or programs ranked by rewards, scope, competition, target quality, or recent target additions without requiring repository activity.",
             minimum_arguments: {},
-            useful_arguments: ["platforms", "target_types", "language_tags", "min_bounty_max", "max_public_report_count", "fresh_launch_days", "has_api_scope"]
+            useful_arguments: ["platforms", "surface_mode", "target_types", "language_tags", "min_bounty_max", "max_public_report_count", "recent_target_days", "ranking_mode"]
         },
         {
             tool: "find_repository_hunt_targets",
@@ -1913,13 +1965,13 @@ function bbradarGuide(topic, profile, client) {
     const decisionTree = [
         {
             user_goal: "find programs to hunt",
-            first_tool: "find_program_candidates",
-            then: "Use get_program_brief on the best program_id if the user wants details."
+            first_tool: "find_hunt_targets",
+            then: "Treat its ranked matches, exact bounded target samples, and recent additions as final unless the user explicitly requests an exhaustive scope dump for one selected program."
         },
         {
             user_goal: "Web2 programs with broad scope, good rewards, recent target activity, and excluded platforms",
-            first_tool: "list_filters",
-            then: "Resolve the excluded platform names, then call find_programs with exclude_platforms, exclude_web3=true, exclude_non_web=true, reward/scope/freshness thresholds, and sort_by=most_new_targets. If strict local filters return zero, relax one threshold and retry; cached source pages make the retry cheap."
+            first_tool: "find_hunt_targets",
+            then: "Call once with surface_mode=web2 and the requested platforms/exclusions. Do not split the platforms or ranking dimensions into separate calls."
         },
         {
             user_goal: "named program summary",
@@ -1991,7 +2043,7 @@ function bbradarGuide(topic, profile, client) {
         }
     ];
     const advancedTools = {
-        discovery: ["find_wildcard_programs", "find_low_competition_high_reward", "find_stack_matches", "find_language_programs", "find_target_type_programs", "find_reward_programs", "find_paid_programs", "find_web3_contests", "find_low_noise_programs"],
+        discovery: ["find_hunt_targets", "find_wildcard_programs", "find_low_competition_high_reward", "find_stack_matches", "find_language_programs", "find_target_type_programs", "find_reward_programs", "find_paid_programs", "find_web3_contests", "find_low_noise_programs"],
         freshness: ["find_recently_added_wildcards", "find_recently_updated_programs", "find_fresh_hunt_candidates", "get_latest_added_targets", "get_recent_target_activity", "get_program_scope_delta", "check_watchlist_new_targets"],
         details: ["get_program_brief", "get_program_scope_summary", "get_program_target_breakdown", "find_programs_by_target"],
         exports: ["export_targets"]
@@ -2064,9 +2116,10 @@ function bbradarGuide(topic, profile, client) {
 function coreBbradarGuide(topic, client) {
     const decisionTree = [
         {
-            user_goal: "find programs to hunt",
-            first_tool: "find_programs",
-            arguments: { max_results: 10, output_mode: "compact" }
+            user_goal: "find good hunt targets or programs using rewards, scope, competition, target quality, or recent target additions",
+            first_tool: "find_hunt_targets",
+            arguments: { max_results: 10, ranking_mode: "balanced" },
+            then: "Use this single result as the final shortlist; do not repeat find_programs with alternate sorts or fetch each program's targets."
         },
         {
             user_goal: "named program targets",
@@ -2102,7 +2155,7 @@ function coreBbradarGuide(topic, client) {
         {
             user_goal: "unknown filter values",
             first_tool: "list_filters",
-            then: "Reuse observed platforms, tags, target types, and language tags in find_programs."
+            then: "Reuse observed platforms, tags, target types, and language tags in one find_hunt_targets call."
         }
     ];
     return {
@@ -2118,6 +2171,7 @@ function coreBbradarGuide(topic, client) {
             require_bounty: true
         },
         primary_entry_points: [
+            "find_hunt_targets",
             "find_programs",
             "find_repository_hunt_targets",
             "run_program_name_action",
@@ -5633,7 +5687,7 @@ function previewExportText(payload) {
 }
 function collectResourceLinks(payload) {
     const links = new Map();
-    for (const program of extractProgramsFromPayload(payload)) {
+    for (const program of extractProgramsFromPayload(payload).slice(0, MAX_BULK_PROGRAM_RESOURCE_LINKS)) {
         const id = stringField(program, "id");
         const resourceLinks = readObject(program.resource_links);
         const programUri = stringField(resourceLinks, "program");
@@ -5981,15 +6035,15 @@ function candidateTradeoffs(candidate) {
 }
 function candidateNextAction(candidate) {
     if (candidate.wildcardCount > 0) {
-        return "Review in-scope wildcard targets with get_program_targets and keep follow-up analysis passive and BBRadar-data-backed.";
+        return "Use included target samples for shortlisting; call get_program_targets only if the user explicitly requests the selected program's exhaustive wildcard scope.";
     }
     if (candidateHasApiSurface(candidate)) {
-        return "Review API targets with get_program_targets and summarize the allowed API scope from BBRadar data.";
+        return "Use included target samples for shortlisting; call get_program_targets only if the user explicitly requests the selected program's exhaustive API scope.";
     }
     if (candidateHasWebSurface(candidate)) {
-        return "Review web/domain targets with get_program_targets and summarize freshness, reward, and report-count signals.";
+        return "Use included target samples for shortlisting; call get_program_targets only if the user explicitly requests the selected program's exhaustive web scope.";
     }
-    return "Fetch exact scope with get_program_targets before making recommendations.";
+    return "The program-level ranking is sufficient for a shortlist; fetch exact scope only if the user requests exhaustive details for this program.";
 }
 function targetSurfaceScore(candidate) {
     return candidate.targetSurfaceScore;
@@ -6294,6 +6348,536 @@ function clampLimit(name, value, max, warnings) {
     warnings.push(`${name} was clamped from ${value} to ${max}.`);
     return max;
 }
+async function findHuntTargets(client, config, input) {
+    const warnings = [];
+    const errors = [];
+    const recentChangesEnabled = input.include_recent_changes && client.supportsEndpoint("target_changes");
+    const desiredRecentChangeQueries = recentChangesEnabled ? huntRecentChangeQueries(input) : [];
+    const recentChangeQueries = desiredRecentChangeQueries.slice(0, Math.max(0, input.upstream_request_budget - 2));
+    const recentRequestReserve = recentChangeQueries.length;
+    const candidatePoolSize = Math.min(MAX_FIND_PROGRAM_RESULTS, Math.max(input.max_results, input.max_results * 3));
+    const programRequestBudget = Math.min(input.max_program_pages, Math.max(1, Math.ceil((input.upstream_request_budget - recentRequestReserve) / 2)));
+    const programInput = {
+        platforms: input.platforms,
+        exclude_platforms: input.exclude_platforms,
+        tags: input.tags,
+        scope_tags: input.scope_tags,
+        target_types: input.target_types,
+        language_tags: input.language_tags,
+        web3: input.surface_mode === "web3",
+        exclude_web3: input.surface_mode === "web2",
+        opportunity_levels: [],
+        updated_since: input.updated_since,
+        min_bounty_min: undefined,
+        min_bounty_max: input.min_bounty_max,
+        max_bounty_max: undefined,
+        require_bounty: input.require_bounty,
+        max_public_report_count: input.max_public_report_count,
+        require_known_report_count: false,
+        include_unknown_report_count: input.include_unknown_report_count,
+        exclude_ctf: true,
+        exclude_mobile_only: input.surface_mode === "web2",
+        exclude_non_web: input.surface_mode === "web2",
+        has_api_scope: false,
+        contest_like: false,
+        vdp_mode: "exclude",
+        fresh_launch_days: input.fresh_launch_days,
+        min_wildcards: input.min_wildcards,
+        min_eligible_targets: input.min_eligible_targets,
+        min_total_targets: input.min_total_targets,
+        min_added_24h: undefined,
+        min_added_7d: input.min_added_7d,
+        max_pages: input.max_program_pages,
+        max_results: candidatePoolSize,
+        sort_by: huntProgramSort(input.ranking_mode),
+        include_target_samples: false,
+        target_sample_programs: 0,
+        target_sample_size: 1,
+        only_in_scope_targets: true,
+        only_bounty_eligible_targets: true,
+        target_samples_only_wildcards: false,
+        output_mode: "compact",
+        upstream_request_budget: programRequestBudget
+    };
+    if (input.include_recent_changes && !recentChangesEnabled) {
+        warnings.push("The negotiated API contract does not expose target changes; ranked current programs without recent-change enrichment.");
+    }
+    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 [programPayload, recentResult] = await Promise.all([
+        findPrograms(client, config, programInput),
+        recentChangesEnabled
+            ? fetchHuntRecentChanges(client, config, input, recentChangeQueries)
+            : Promise.resolve({ changes: [], sourceRequests: [], requestsUsed: 0, errors: [] })
+    ]);
+    const programWarnings = readArray(programPayload.warnings).filter((warning) => typeof warning === "string");
+    warnings.push(...programWarnings);
+    errors.push(...recentResult.errors);
+    const programBudget = readObject(programPayload.upstream_budget);
+    const programRequestsUsed = readNumber(programBudget?.used) ?? 0;
+    const targetRequestBudget = Math.max(0, input.upstream_request_budget - programRequestsUsed - recentResult.requestsUsed);
+    const programEntries = readArray(programPayload.programs)
+        .map(readObject)
+        .filter((program) => program !== undefined);
+    const recentByProgram = groupRecentHuntChanges(recentResult.changes, input);
+    const preliminaryRankedEntries = programEntries
+        .map((entry) => ({
+        entry,
+        ranking: buildHuntTargetMatch(entry, new Map(), recentByProgram, input)
+    }))
+        .sort((left, right) => compareHuntTargetMatches(left.ranking, right.ranking, input.ranking_mode));
+    const sampledProgramCount = Math.min(input.max_results, preliminaryRankedEntries.length, targetRequestBudget);
+    const finalistEntries = preliminaryRankedEntries
+        .slice(0, sampledProgramCount)
+        .map((entry) => entry.entry);
+    const targetResult = await collectHuntTargetSamples(client, finalistEntries, input);
+    errors.push(...targetResult.errors);
+    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.`);
+    }
+    const ranked = finalistEntries
+        .map((entry) => buildHuntTargetMatch(entry, targetResult.targetsByProgram, recentByProgram, input))
+        .sort((left, right) => compareHuntTargetMatches(left, right, input.ranking_mode))
+        .slice(0, input.max_results);
+    const matches = ranked.map((entry, index) => ({
+        rank: index + 1,
+        ...entry.payload
+    }));
+    const targetRequestsUsed = targetResult.requestsUsed;
+    const totalRequestsUsed = programRequestsUsed + recentResult.requestsUsed + targetRequestsUsed;
+    return stripUndefined({
+        request_id: randomUUID(),
+        fetched_at: new Date().toISOString(),
+        source_requests: [
+            ...readArray(programPayload.source_requests),
+            ...recentResult.sourceRequests,
+            ...targetResult.sourceRequests
+        ],
+        warnings: uniqueStrings(warnings).length > 0 ? uniqueStrings(warnings) : undefined,
+        errors: errors.length > 0 ? errors : undefined,
+        filters: stripUndefined({
+            platforms: input.platforms.length > 0 ? input.platforms : undefined,
+            exclude_platforms: input.exclude_platforms.length > 0 ? input.exclude_platforms : undefined,
+            tags: input.tags.length > 0 ? input.tags : undefined,
+            scope_tags: input.scope_tags.length > 0 ? input.scope_tags : undefined,
+            target_types: input.target_types.length > 0 ? input.target_types : undefined,
+            language_tags: input.language_tags.length > 0 ? input.language_tags : undefined,
+            surface_mode: input.surface_mode,
+            min_bounty_max: input.min_bounty_max,
+            require_bounty: input.require_bounty,
+            max_public_report_count: input.max_public_report_count,
+            min_eligible_targets: input.min_eligible_targets,
+            min_total_targets: input.min_total_targets,
+            min_wildcards: input.min_wildcards,
+            min_added_7d: input.min_added_7d,
+            fresh_launch_days: input.fresh_launch_days,
+            updated_since: input.updated_since,
+            min_target_score: input.min_target_score,
+            target_opportunity_label: input.target_opportunity_label,
+            competition_risk: input.competition_risk,
+            recent_target_days: input.include_recent_changes ? input.recent_target_days : undefined,
+            ranking_mode: input.ranking_mode
+        }),
+        upstream_budget: {
+            initial: input.upstream_request_budget,
+            used: totalRequestsUsed,
+            remaining: Math.max(0, input.upstream_request_budget - totalRequestsUsed)
+        },
+        ranking_scope: stripUndefined({
+            ...(readObject(programPayload.ranking_scope) ?? {}),
+            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
+        }),
+        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."
+        },
+        matches,
+        meta: {
+            returned: matches.length,
+            program_candidates: programEntries.length,
+            exact_target_programs_sampled: targetResult.targetsByProgram.size,
+            recent_changes_scanned: recentResult.changes.length,
+            recent_programs_matched: recentByProgram.size,
+            model_round_trips_expected: 1,
+            parallel_recent_change_fetch: recentChangeQueries.length > 0,
+            bulk_resource_links_suppressed: true,
+            partial_success: errors.length > 0
+        }
+    });
+}
+function huntProgramSort(mode) {
+    if (mode === "highest_reward") {
+        return "highest_reward";
+    }
+    if (mode === "widest_scope") {
+        return "most_eligible_targets";
+    }
+    if (mode === "freshest_targets") {
+        return "most_new_targets";
+    }
+    if (mode === "lowest_competition") {
+        return "lowest_reports";
+    }
+    return "best_hunt_value";
+}
+async function fetchHuntRecentChanges(client, config, input, targetTypes) {
+    const results = await Promise.all(targetTypes.map(async (targetType) => {
+        try {
+            const api = await client.getRecentChanges(toQuery({
+                change_type: "added",
+                minTargetScore: input.min_target_score,
+                targetOpportunityLabel: input.target_opportunity_label,
+                competitionRisk: input.competition_risk,
+                include_removed: false,
+                include_ineligible: false,
+                include_out_of_scope: false,
+                platforms: input.platforms,
+                tags: targetType ? [targetType] : undefined,
+                page: 1,
+                page_size: input.recent_changes_page_size
+            }));
+            const data = readObject(api.data);
+            return {
+                changes: readArray(data?.results).map((change) => sanitizeChange(change, config.webBaseUrl)),
+                sourceRequest: {
+                    source: "recent_changes",
+                    target_type: targetType,
+                    request_id: api.requestId,
+                    upstream_request_id: api.upstreamRequestId,
+                    ...apiSourceMetadata(api),
+                    page: 1
+                },
+                requestsUsed: api.cached || api.coalesced ? 0 : 1,
+                error: undefined
+            };
+        }
+        catch (error) {
+            return {
+                changes: [],
+                sourceRequest: undefined,
+                requestsUsed: error instanceof BBRadarApiError && (error.cached || error.coalesced) ? 0 : 1,
+                error: apiOperationError(targetType ? `recent ${targetType} target changes` : "recent target changes", error)
+            };
+        }
+    }));
+    const changes = new Map();
+    for (const result of results) {
+        for (const change of result.changes) {
+            const id = readNumber(change.id) ?? stringField(change, "id");
+            const target = readObject(change.target);
+            const program = readObject(change.program);
+            const fallbackKey = `${stringField(program, "id") ?? ""}:${targetIdentifier(target ?? {}) ?? ""}:${stringField(change, "changed_at") ?? ""}`;
+            changes.set(id === undefined ? fallbackKey : String(id), change);
+        }
+    }
+    return {
+        changes: [...changes.values()],
+        sourceRequests: results
+            .map((result) => result.sourceRequest)
+            .filter((request) => request !== undefined),
+        requestsUsed: results.reduce((total, result) => total + result.requestsUsed, 0),
+        errors: results
+            .map((result) => result.error)
+            .filter((error) => error !== undefined)
+    };
+}
+function huntRecentChangeQueries(input) {
+    const requested = uniqueStrings(input.target_types);
+    if (requested.length > 0 && requested.length <= 3) {
+        return requested;
+    }
+    if (requested.length > 3) {
+        return [undefined];
+    }
+    if (input.surface_mode === "web2") {
+        return ["domain", "api", "wildcard"];
+    }
+    if (input.surface_mode === "web3") {
+        return ["source code", "smart contract", "blockchain-dlt"];
+    }
+    return [undefined];
+}
+async function collectHuntTargetSamples(client, programs, input) {
+    const targetsByProgram = new Map();
+    const sourceRequestsByIndex = new Array(programs.length);
+    const errorsByIndex = new Array(programs.length);
+    let requestsUsed = 0;
+    await mapWithConcurrency(programs.map((program, index) => ({ program, index })), TARGET_SAMPLE_CONCURRENCY, async ({ program, index }) => {
+        const programId = stringField(program, "id");
+        if (!programId) {
+            return;
+        }
+        try {
+            const requestedPageSize = Math.max(input.targets_per_result, input.target_types.length > 1 ? input.targets_per_result * 10 : input.targets_per_result * 4, 20);
+            const api = await client.getProgramTargets(programId, {
+                target_type: input.target_types.length === 1 ? input.target_types[0] : undefined,
+                eligibility: "eligible",
+                minTargetScore: input.min_target_score,
+                targetOpportunityLabel: input.target_opportunity_label,
+                competitionRisk: input.competition_risk,
+                page: 1,
+                page_size: Math.min(client.endpointNumber("program_targets", "max_page_size", MAX_TARGETS_PER_PROGRAM), requestedPageSize)
+            });
+            const data = readObject(api.data);
+            const matchingTargets = readArray(data?.targets)
+                .map(sanitizeTarget)
+                .filter((target) => huntTargetMatches(target, input));
+            const targets = selectHuntTargetSamples(matchingTargets, input.targets_per_result, input.recent_target_days);
+            targetsByProgram.set(programId, targets);
+            sourceRequestsByIndex[index] = {
+                source: "program_targets",
+                program_id: programId,
+                request_id: api.requestId,
+                upstream_request_id: api.upstreamRequestId,
+                ...apiSourceMetadata(api)
+            };
+            if (!api.cached && !api.coalesced) {
+                requestsUsed += 1;
+            }
+        }
+        catch (error) {
+            errorsByIndex[index] = apiOperationError(programId, error);
+            if (!(error instanceof BBRadarApiError) || (!error.cached && !error.coalesced)) {
+                requestsUsed += 1;
+            }
+        }
+    });
+    return {
+        targetsByProgram,
+        sourceRequests: sourceRequestsByIndex.filter((request) => request !== undefined),
+        requestsUsed,
+        errors: errorsByIndex.filter((error) => error !== undefined)
+    };
+}
+function huntTargetMatches(target, input) {
+    if (target.in_scope !== true || target.eligible_for_bounty !== true) {
+        return false;
+    }
+    if (input.target_types.length > 0 && !input.target_types.some((targetType) => targetMatchesRequestedType(target, targetType))) {
+        return false;
+    }
+    if (input.scope_tags.length > 0 && !arraysIntersectNormalized(new Set(input.scope_tags.map(normalizeTag)), readStringArrayField(target, "scope_tags"))) {
+        return false;
+    }
+    if (input.language_tags.length > 0 && !arraysIntersectNormalized(new Set(input.language_tags.map(normalizeTag)), readStringArrayField(target, "language_tags"))) {
+        return false;
+    }
+    if (input.min_target_score !== undefined && (readNumber(target.target_opportunity_score) ?? -1) < input.min_target_score) {
+        return false;
+    }
+    if (input.target_opportunity_label !== undefined && stringField(target, "target_opportunity_label") !== input.target_opportunity_label) {
+        return false;
+    }
+    if (input.competition_risk !== undefined && stringField(target, "competition_risk") !== input.competition_risk) {
+        return false;
+    }
+    return true;
+}
+function compareHuntTargets(left, right) {
+    return (compareNumbersDesc(readNumber(left.target_opportunity_score), readNumber(right.target_opportunity_score)) ||
+        Number(readBoolean(right.wildcard) === true) - Number(readBoolean(left.wildcard) === true) ||
+        (targetIdentifier(left) ?? "").localeCompare(targetIdentifier(right) ?? ""));
+}
+function selectHuntTargetSamples(targets, limit, recentTargetDays) {
+    const selected = new Map();
+    const cutoff = Date.now() - recentTargetDays * 24 * 60 * 60 * 1000;
+    const newest = [...targets]
+        .filter((target) => huntTargetAddedTimestamp(target) >= cutoff)
+        .sort((left, right) => huntTargetAddedTimestamp(right) - huntTargetAddedTimestamp(left));
+    const byQuality = [...targets].sort(compareHuntTargets);
+    for (const target of newest.slice(0, Math.min(2, limit))) {
+        const identifier = targetIdentifier(target);
+        if (identifier) {
+            selected.set(identifier, target);
+        }
+    }
+    for (const target of byQuality) {
+        if (selected.size >= limit) {
+            break;
+        }
+        const identifier = targetIdentifier(target);
+        if (identifier && !selected.has(identifier)) {
+            selected.set(identifier, target);
+        }
+    }
+    return [...selected.values()];
+}
+function huntTargetAddedTimestamp(target) {
+    const addedAt = stringField(target, "added_at") ?? stringField(target, "source_added_at");
+    const timestamp = addedAt ? Date.parse(addedAt) : Number.NaN;
+    return Number.isFinite(timestamp) ? timestamp : 0;
+}
+function groupRecentHuntChanges(changes, input) {
+    const cutoff = Date.now() - input.recent_target_days * 24 * 60 * 60 * 1000;
+    const byProgram = new Map();
+    for (const change of changes) {
+        if (stringField(change, "change_type") !== "added" || timestampField(change, "changed_at") < cutoff) {
+            continue;
+        }
+        const program = readObject(change.program);
+        const target = readObject(change.target);
+        const programId = stringField(program, "id");
+        if (!programId || !target || !huntTargetMatches(target, input)) {
+            continue;
+        }
+        const existing = byProgram.get(programId) ?? [];
+        const identifier = targetIdentifier(target);
+        if (!identifier || !existing.some((entry) => targetIdentifier(readObject(entry.target) ?? {}) === identifier)) {
+            existing.push(change);
+            existing.sort((left, right) => timestampField(right, "changed_at") - timestampField(left, "changed_at"));
+            byProgram.set(programId, existing);
+        }
+    }
+    return byProgram;
+}
+function buildHuntTargetMatch(entry, targetsByProgram, recentByProgram, input) {
+    const programId = stringField(entry, "id") ?? "";
+    const targetSamples = targetsByProgram.get(programId) ?? [];
+    const recentChanges = recentByProgram.get(programId) ?? [];
+    const recentTargets = recentHuntTargetEntries(targetSamples, recentChanges, input.recent_target_days);
+    const rankFactors = readObject(entry.rank_factors) ?? {};
+    const latestRecentAt = recentTargets[0]?.addedAt;
+    const rewardScore = normalizedRewardScore(readNumber(rankFactors.bounty_max));
+    const scopeScore = Math.min(100, (readNumber(rankFactors.eligible_targets) ?? 0) * 2 +
+        (readNumber(rankFactors.wildcard_targets) ?? 0) * 5 +
+        (readNumber(rankFactors.target_surface_score) ?? 0) * 0.25);
+    const freshnessScore = huntFreshnessScore(latestRecentAt, recentTargets.length, readNumber(rankFactors.added_7d));
+    const publicReports = readNumber(rankFactors.public_report_count);
+    const competitionScore = publicReports === undefined ? 50 : Math.max(0, 100 - Math.min(100, publicReports / 10));
+    const bestTargetScore = Math.max(0, ...targetSamples.map((target) => readNumber(target.target_opportunity_score) ?? 0));
+    const baseHuntScore = readNumber(rankFactors.hunt_value_score) ?? 0;
+    const compositeScore = huntCompositeScore(input.ranking_mode, baseHuntScore, rewardScore, scopeScore, freshnessScore, competitionScore, bestTargetScore);
+    const program = compactProgram(entry);
+    delete program.resource_links;
+    const existingReasons = readArray(entry.why_ranked_here).filter((reason) => typeof reason === "string");
+    const reasons = [...existingReasons];
+    if (recentTargets.length > 0) {
+        reasons.push(`${recentTargets.length} eligible target additions in the last ${input.recent_target_days} days`);
+    }
+    if (bestTargetScore > 0) {
+        reasons.push(`best sampled target score ${bestTargetScore}`);
+    }
+    return {
+        compositeScore,
+        rewardScore,
+        scopeScore,
+        freshnessScore,
+        competitionScore,
+        payload: stripUndefined({
+            program,
+            match_score: compositeScore,
+            rank_factors: {
+                ...rankFactors,
+                reward_score: roundScore(rewardScore),
+                scope_score: roundScore(scopeScore),
+                freshness_score: roundScore(freshnessScore),
+                competition_score: roundScore(competitionScore),
+                best_sample_target_score: bestTargetScore > 0 ? bestTargetScore : undefined,
+                recent_added_targets_in_window: recentTargets.length,
+                latest_added_target_at: latestRecentAt,
+                composite_score: compositeScore
+            },
+            why_ranked_here: uniqueStrings(reasons),
+            tradeoffs: readArray(entry.tradeoffs).filter((tradeoff) => typeof tradeoff === "string"),
+            target_samples: targetSamples.map(compactHuntTarget),
+            recent_added_targets: recentTargets.slice(0, input.targets_per_result).map((recent) => ({
+                ...compactHuntTarget(recent.target),
+                added_at: recent.addedAt,
+                freshness_source: recent.source
+            }))
+        })
+    };
+}
+function compactHuntTarget(target) {
+    return stripUndefined({
+        ...compactTarget(target),
+        added_at: stringField(target, "added_at"),
+        source_added_at: stringField(target, "source_added_at"),
+        last_changed_at: stringField(target, "last_changed_at")
+    });
+}
+function recentHuntTargetEntries(targetSamples, recentChanges, recentTargetDays) {
+    const cutoff = Date.now() - recentTargetDays * 24 * 60 * 60 * 1000;
+    const entries = new Map();
+    const remember = (target, addedAt, source) => {
+        const identifier = targetIdentifier(target);
+        const timestamp = addedAt ? Date.parse(addedAt) : Number.NaN;
+        if (!identifier || !addedAt || !Number.isFinite(timestamp) || timestamp < cutoff) {
+            return;
+        }
+        const existing = entries.get(identifier);
+        if (!existing || timestamp > existing.timestamp || (timestamp === existing.timestamp && source === "target_change")) {
+            entries.set(identifier, { target, addedAt, source, timestamp });
+        }
+    };
+    for (const change of recentChanges) {
+        const target = readObject(change.target);
+        if (target) {
+            remember(target, stringField(change, "changed_at"), "target_change");
+        }
+    }
+    for (const target of targetSamples) {
+        remember(target, stringField(target, "added_at") ?? stringField(target, "source_added_at"), "target_inventory");
+    }
+    return [...entries.values()].sort((left, right) => right.timestamp - left.timestamp);
+}
+function normalizedRewardScore(reward) {
+    if (reward === undefined || reward <= 0) {
+        return 0;
+    }
+    return Math.min(100, Math.log10(reward + 1) / Math.log10(100_001) * 100);
+}
+function huntFreshnessScore(latestAt, recentCount, added7d) {
+    if (latestAt) {
+        const timestamp = Date.parse(latestAt);
+        if (Number.isFinite(timestamp)) {
+            const ageDays = Math.max(0, (Date.now() - timestamp) / (24 * 60 * 60 * 1000));
+            return Math.min(100, Math.max(0, 100 - ageDays * 2) + Math.min(20, recentCount * 4));
+        }
+    }
+    return Math.min(100, Math.max(0, added7d ?? 0) * 12);
+}
+function huntCompositeScore(mode, baseHuntScore, rewardScore, scopeScore, freshnessScore, competitionScore, bestTargetScore) {
+    if (mode === "highest_reward") {
+        return roundScore(rewardScore * 0.7 + baseHuntScore * 0.2 + scopeScore * 0.1);
+    }
+    if (mode === "widest_scope") {
+        return roundScore(scopeScore * 0.7 + baseHuntScore * 0.2 + rewardScore * 0.1);
+    }
+    if (mode === "freshest_targets") {
+        return roundScore(freshnessScore * 0.7 + bestTargetScore * 0.15 + baseHuntScore * 0.15);
+    }
+    if (mode === "lowest_competition") {
+        return roundScore(competitionScore * 0.65 + baseHuntScore * 0.2 + rewardScore * 0.15);
+    }
+    return roundScore(baseHuntScore * 0.35 +
+        rewardScore * 0.2 +
+        scopeScore * 0.2 +
+        freshnessScore * 0.15 +
+        bestTargetScore * 0.1);
+}
+function roundScore(value) {
+    return Math.round(value * 100) / 100;
+}
+function compareHuntTargetMatches(left, right, mode) {
+    if (mode === "highest_reward") {
+        return right.rewardScore - left.rewardScore || right.compositeScore - left.compositeScore;
+    }
+    if (mode === "widest_scope") {
+        return right.scopeScore - left.scopeScore || right.compositeScore - left.compositeScore;
+    }
+    if (mode === "freshest_targets") {
+        return right.freshnessScore - left.freshnessScore || right.compositeScore - left.compositeScore;
+    }
+    if (mode === "lowest_competition") {
+        return right.competitionScore - left.competitionScore || right.compositeScore - left.compositeScore;
+    }
+    return right.compositeScore - left.compositeScore;
+}
 async function findRepositoryHuntTargets(client, config, input) {
     const warnings = [];
     const repositoryRequestReserve = input.upstream_request_budget >= 3 ? 2 : 1;
@@ -7490,9 +8074,11 @@ function readStringArrayField(value, field) {
 }
 function registerPrompts(server, profile) {
     const discoveryToolInstructions = profile === "core"
-        ? `- Start with find_programs and pass opportunity_levels from the requested value below unless the user asked for a broader search.
-- Express language, target type, reward, Web3, wildcard, VDP, and platform needs through find_programs filters.`
-        : `- Start with find_program_candidates unless the user needs custom filters; pass opportunity_levels from the requested value below.
+        ? `- Start with find_hunt_targets for ranked target/program discovery. Make one call and use its shortlist as final; do not repeat find_programs with alternate sorts or fetch each candidate's targets.
+- Express language, target type, reward, Web2/Web3, wildcard, competition, freshness, and platform needs through find_hunt_targets filters.
+- Use find_repository_hunt_targets instead when the user explicitly requires Git or repository activity.`
+        : `- Start with find_hunt_targets for ranked target/program discovery; use its included target samples and recent additions as the final shortlist.
+- Use find_program_candidates only for lower-level program-only discovery; pass opportunity_levels from the requested value below.
 - Use find_language_programs for language asks, find_target_type_programs for API/mobile/source-code/domain asks, find_reward_programs or find_paid_programs for reward asks, find_vdp_programs only for explicit VDP/no-bounty asks, find_web3_contests for Web3 contest/audit asks, find_web3_programs for general Web3 requests, and find_wildcard_programs for wildcard-specific requests.`;
     server.registerPrompt("find_best_programs_to_hunt", {
         title: "Find Best Programs To Hunt",
@@ -7507,7 +8093,7 @@ function registerPrompts(server, profile) {
 
 Find the best BBRadar program candidates.
 ${discoveryToolInstructions}
-- Use this opportunity level JSON array: ${promptJson([args.opportunity_level ?? "elite"])}.
+- Treat this opportunity level JSON array as a ranking preference, not a strict first-pass filter: ${promptJson([args.opportunity_level ?? "elite"])}.
 - Apply platform filters from this JSON string if provided: ${promptJson(args.platforms ?? "")}.
 - Apply tag filters from this JSON string if provided: ${promptJson(args.tags ?? "")}.
 - Keep the shortlist to this JSON value: ${promptJson(args.max_programs ?? "10")}.