@bbradar/mcp 0.2.0 → 0.2.1

package/README.md

@@ -131,7 +131,7 @@ Large target and change collections return at most 50 inline records by default.
 
 ## Performance Tuning
 
-The defaults expose the 16-tool core surface and compact text results while enabling bounded concurrency, positive response caching, in-flight request coalescing, stale-while-revalidate program metadata, endpoint circuit breakers, and short negative caching for repeated 404/405 lookups. Set the tool profile to `full` when all specialized tools are needed.
+The defaults expose the 17-tool core surface and compact text results while enabling bounded concurrency, positive response caching, in-flight request coalescing, stale-while-revalidate program metadata, endpoint circuit breakers, and short negative caching for repeated 404/405 lookups. Set the tool profile to `full` when all specialized tools are needed.
 
 | Environment variable | Default | Purpose |
 | --- | ---: | --- |
@@ -141,7 +141,7 @@ The defaults expose the 16-tool core surface and compact text results while enab
 | `BBRADAR_MCP_MAX_CONCURRENT_REQUESTS` | `6` | Maximum simultaneous upstream BBRadar API requests. |
 | `BBRADAR_MCP_REQUEST_TIMEOUT_SECONDS` | `30` | Timeout for each active upstream request; queue time is excluded. |
 | `BBRADAR_MCP_COMPACT_TOOL_TEXT` | `true` | Avoid duplicating full results for clients that consume MCP `structuredContent`. Set to `false` for legacy text-only clients. |
-| `BBRADAR_MCP_TOOL_PROFILE` | `core` | Compact 16-tool discovery surface. Set to `full` for every specialized tool. |
+| `BBRADAR_MCP_TOOL_PROFILE` | `core` | Compact 17-tool discovery surface. Set to `full` for every specialized tool. |
 | `BBRADAR_MCP_PROGRAM_STALE_WHILE_REVALIDATE_SECONDS` | `300` | Maximum stale window for exact program metadata while one background refresh runs. |
 | `BBRADAR_MCP_CIRCUIT_BREAKER_FAILURE_THRESHOLD` | `3` | Consecutive retryable endpoint failures before its circuit opens. |
 | `BBRADAR_MCP_CIRCUIT_BREAKER_COOLDOWN_SECONDS` | `30` | Endpoint circuit cooldown before a new request is admitted. |
@@ -164,7 +164,7 @@ Run `npm run benchmark` for the deterministic local performance benchmark. It re
 
 Use `find_programs` as the generic ranked path for combinations of platform, reward, opportunity, scope breadth, technology, competition, and freshness signals. It supports both inclusion and exclusion through `platforms`, `exclude_platforms`, `web3`, `exclude_web3`, and the remaining scope/reward/activity filters. When a user describes an exclusion without naming exact platform values, call `list_filters` first and reuse the observed values. If an intentionally strict combination returns no candidates, relax one local threshold at a time; the upstream program pages are cached, so these fallback passes normally add no API requests.
 
-For repository-aware hunting, call `get_repository_changes` and `find_programs` in parallel with the same requested platform set. The repository feed supplies recent events and scored targets while `find_programs` supplies reward and ranking data. Intersect their program ids, discard non-requested programs that merely share the same repository, and treat targets as event-level associations when the feed omits `program_id`. This remains generic across platforms and technology stacks and avoids a specialized tool for every prompt variation.
+For repository-aware hunting, use `find_repository_hunt_targets`. It fetches repository events and program/reward candidates concurrently inside one MCP call, joins them by program id, filters scored targets, removes non-requested associated platforms, and ranks the final matches by a balanced, reward-first, target-first, or recency-first strategy. The inputs remain generic across platforms and technology stacks, so the AI client does not need to plan and wait for a long sequence of separate calls.
 
 ### Optimized wildcard discovery
 
@@ -192,6 +192,7 @@ This path uses one recent-changes request. Use `find_wildcard_programs` for a ra
 - `get_program_targets`
 - `get_recent_changes`
 - `get_repository_changes`
+- `find_repository_hunt_targets`
 - `get_opportunities`
 - `find_programs`
 - `find_wildcard_programs`

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.0";
+const SERVER_VERSION = "0.2.1";
 const MAX_PROGRAMS_PER_SEARCH = 100;
 const MAX_TARGET_EXPORT = 500;
 const MAX_RECENT_CHANGES = 100;
@@ -50,6 +50,7 @@ const CORE_TOOL_NAMES = new Set([
     "get_program_targets",
     "get_recent_changes",
     "get_repository_changes",
+    "find_repository_hunt_targets",
     "get_latest_added_targets",
     "get_opportunities",
     "find_programs",
@@ -61,6 +62,7 @@ const CORE_TOOL_NAMES = new Set([
 ]);
 const TOOL_ENDPOINT_REQUIREMENTS = {
     get_repository_changes: "repository_changes",
+    find_repository_hunt_targets: "repository_changes",
     export_targets: "target_export",
     get_opportunities: "opportunities"
 };
@@ -682,7 +684,7 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("get_repository_changes", {
         title: "Get Repository Changes",
-        description: "Read-only repository push/change feed. Defaults to lightweight program summaries; use after_id for efficient incremental polling. For rewarded Web3 repository targets, call this in parallel with find_programs using the same platforms, then intersect event program ids with the ranked rewarded programs.",
+        description: "Read-only repository push/change feed for direct inspection or polling. Defaults to lightweight program summaries; use after_id for efficient incremental polling. Use find_repository_hunt_targets instead when reward or target-quality ranking is also required.",
         inputSchema: {
             after_id: z.number().int().min(0).optional().describe("Incremental cursor; returns events after this id in ascending order."),
             resume_cursor: z.boolean().default(false).describe("Resume the in-memory cursor for this exact normalized filter set. Seed it once with after_id."),
@@ -739,6 +741,51 @@ export function createBbradarServer(client, config) {
             source_requests: collected.sourceRequests.length > 1 ? collected.sourceRequests : undefined
         }), "repository_changes", "repository changes", continuationStore, config);
     }));
+    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.",
+        inputSchema: {
+            platforms: platformListSchema(),
+            exclude_platforms: stringListSchema("Platforms to exclude from final matches."),
+            tags: tagListSchema(),
+            scope_tags: scopeTagListSchema(),
+            target_types: targetTypeListSchema(),
+            language_tags: languageTagListSchema(),
+            surface_mode: z.enum(["any", "web2", "web3"]).default("any"),
+            opportunity_levels: z.array(opportunityLevelSchema).max(4).default([]),
+            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(1),
+            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(),
+            changed_since: isoDateTimeSchema.optional(),
+            free_submission_only: z.boolean().default(false),
+            min_target_score: z.number().int().min(0).max(100).default(60),
+            target_opportunity_labels: z.array(targetOpportunityLabelSchema).max(4).default([]),
+            competition_risks: z.array(competitionRiskSchema).max(4).default([]),
+            max_program_pages: z.number().int().min(1).max(MAX_FIND_PROGRAM_PAGES).default(3),
+            max_program_candidates: z.number().int().min(1).max(MAX_FIND_PROGRAM_RESULTS).default(MAX_FIND_PROGRAM_RESULTS),
+            repository_page_size: z.number().int().min(1).max(maxRepositoryChangesPageSize).default(Math.min(100, maxRepositoryChangesPageSize)),
+            max_results: z.number().int().min(1).max(25).default(10),
+            max_targets_per_result: z.number().int().min(1).max(20).default(5),
+            ranking_mode: z.enum(["balanced", "highest_reward", "best_target", "newest"]).default("balanced"),
+            output_mode: repositoryChangeListModeSchema.default("compact"),
+            upstream_request_budget: z.number().int().min(2).max(MAX_FIND_UPSTREAM_REQUEST_BUDGET).default(10)
+        },
+        outputSchema: {
+            ...apiEnvelopeOutputShape(),
+            matches: z.array(jsonRecordSchema()).optional(),
+            programs: z.array(jsonRecordSchema()).optional(),
+            filters: jsonRecordSchema().optional(),
+            upstream_budget: jsonRecordSchema().optional(),
+            ranking_scope: jsonRecordSchema().optional(),
+            meta: jsonRecordSchema().optional()
+        },
+        annotations: readOnlyAnnotations
+    }, (args) => runTool("find_repository_hunt_targets", config, rateLimiter, async () => findRepositoryHuntTargets(client, config, args)));
     registerTool("get_latest_added_targets", {
         title: "Get Latest Added Targets",
         description: "Latest added targets by type with optional platform, reward, and report-count filters. For fast wildcard discovery use target_type=wildcard and include_full_target_list=false.",
@@ -1839,6 +1886,12 @@ function bbradarGuide(topic, profile, client) {
             minimum_arguments: {},
             useful_arguments: ["platforms", "target_types", "language_tags", "min_bounty_max", "max_public_report_count", "fresh_launch_days", "has_api_scope"]
         },
+        {
+            tool: "find_repository_hunt_targets",
+            use_when: "The request combines repository activity with reward, target-quality, platform, technology, or freshness filters.",
+            minimum_arguments: {},
+            useful_arguments: ["platforms", "exclude_platforms", "surface_mode", "min_bounty_max", "min_target_score", "changed_since", "ranking_mode"]
+        },
         {
             tool: "run_program_name_action",
             use_when: "The user names one program and asks for a brief, targets, new targets, scope delta, or target breakdown.",
@@ -1895,14 +1948,10 @@ function bbradarGuide(topic, profile, client) {
             then: "For incremental polling, seed once with after_id and later set resume_cursor=true with the same filters."
         },
         {
-            user_goal: "rewarded Web3 targets with recent repository changes on named platforms",
-            first_tool: "get_repository_changes",
-            arguments: { platforms: ["requested platforms"], include_targets: true, output_mode: "full", page_size: 100 },
-            parallel_with: {
-                tool: "find_programs",
-                arguments: { platforms: ["requested platforms"], web3: true, require_bounty: true, min_bounty_max: 5000, sort_by: "highest_reward", include_target_samples: false }
-            },
-            then: "Intersect repository-event program ids with ranked program ids. Targets belong to the repository event association even when target rows omit program_id; keep strong target scores/labels and only the requested program platforms."
+            user_goal: "hunt targets combining repository activity with rewards, target quality, platforms, or Web2/Web3 constraints",
+            first_tool: "find_repository_hunt_targets",
+            arguments: { platforms: ["requested platforms"], surface_mode: "web3", min_bounty_max: 5000, min_target_score: 60 },
+            then: "Use this single composite call instead of manually chaining program discovery and repository tools. Omit or change any example filter the user did not request."
         },
         {
             user_goal: "latest added wildcard targets with platform, reward, or report-count filters",
@@ -2019,16 +2068,6 @@ function coreBbradarGuide(topic, client) {
             first_tool: "find_programs",
             arguments: { max_results: 10, output_mode: "compact" }
         },
-        {
-            user_goal: "Web2 programs with broad scope, good rewards, recent target activity, and excluded platforms",
-            first_tool: "list_filters",
-            then: "Resolve 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. Relax one local threshold on an empty result; cached source pages make retries fast."
-        },
-        {
-            user_goal: "named program summary or action",
-            first_tool: "run_program_name_action",
-            arguments: { query: "program name", action: "brief" }
-        },
         {
             user_goal: "named program targets",
             first_tool: "get_program_eligible_targets_by_name",
@@ -2050,14 +2089,10 @@ function coreBbradarGuide(topic, client) {
             arguments: { include_targets: false, max_cursor_pages: 2 }
         },
         {
-            user_goal: "rewarded Web3 targets with recent repository changes on named platforms",
-            first_tool: "get_repository_changes",
-            arguments: { platforms: ["requested platforms"], include_targets: true, output_mode: "full", page_size: 100 },
-            parallel_with: {
-                tool: "find_programs",
-                arguments: { platforms: ["requested platforms"], web3: true, require_bounty: true, min_bounty_max: 5000, sort_by: "highest_reward", include_target_samples: false }
-            },
-            then: "Intersect event program ids with ranked program ids. Treat targets as event-level associations when target rows omit program_id, keep strong target scores/labels, and discard non-requested associated platforms."
+            user_goal: "hunt targets combining repository activity with rewards, target quality, platforms, or Web2/Web3 constraints",
+            first_tool: "find_repository_hunt_targets",
+            arguments: { platforms: ["requested platforms"], surface_mode: "web3", min_bounty_max: 5000, min_target_score: 60 },
+            then: "Use this one call instead of manually chaining program and repository tools. Omit or change any example filter the user did not request."
         },
         {
             user_goal: "export targets",
@@ -2084,6 +2119,7 @@ function coreBbradarGuide(topic, client) {
         },
         primary_entry_points: [
             "find_programs",
+            "find_repository_hunt_targets",
             "run_program_name_action",
             "get_program_eligible_targets_by_name",
             "find_programs_by_target",
@@ -6258,6 +6294,285 @@ function clampLimit(name, value, max, warnings) {
     warnings.push(`${name} was clamped from ${value} to ${max}.`);
     return max;
 }
+async function findRepositoryHuntTargets(client, config, input) {
+    const warnings = [];
+    const repositoryRequestReserve = input.upstream_request_budget >= 3 ? 2 : 1;
+    const programRequestBudget = Math.max(1, input.upstream_request_budget - repositoryRequestReserve);
+    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: input.opportunity_levels,
+        updated_since: undefined,
+        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: false,
+        exclude_non_web: input.surface_mode === "web2",
+        has_api_scope: false,
+        contest_like: false,
+        vdp_mode: "exclude",
+        fresh_launch_days: undefined,
+        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: input.max_program_candidates,
+        sort_by: "highest_reward",
+        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
+    };
+    const [programPayload, repository] = await Promise.all([
+        findPrograms(client, config, programInput),
+        fetchRepositoryHuntPage(client, input, warnings, repositoryRequestReserve)
+    ]);
+    const candidatePrograms = readArray(programPayload.programs)
+        .map(readObject)
+        .filter((program) => program !== undefined);
+    const candidatesById = new Map(candidatePrograms
+        .map((program) => [stringField(program, "id"), program])
+        .filter((entry) => entry[0] !== undefined));
+    const changedSinceTime = input.changed_since ? Date.parse(input.changed_since) : undefined;
+    const rankedMatches = [];
+    let qualifyingTargetCount = 0;
+    for (const rawChange of readArray(readObject(repository.api.data)?.results)) {
+        const change = sanitizeRepositoryChange(rawChange, config.webBaseUrl);
+        const observedAtText = stringField(change, "observed_at");
+        const observedAt = observedAtText ? Date.parse(observedAtText) : 0;
+        if (changedSinceTime !== undefined && (!Number.isFinite(observedAt) || observedAt < changedSinceTime)) {
+            continue;
+        }
+        const programs = readArray(change.programs)
+            .map((program) => stringField(readObject(program), "id"))
+            .filter((id) => id !== undefined)
+            .map((id) => candidatesById.get(id))
+            .filter((program) => program !== undefined);
+        if (programs.length === 0) {
+            continue;
+        }
+        const targets = readArray(change.targets)
+            .map(readObject)
+            .filter((target) => target !== undefined)
+            .filter((target) => repositoryHuntTargetMatches(target, input))
+            .sort((left, right) => (readNumber(right.target_opportunity_score) ?? 0) - (readNumber(left.target_opportunity_score) ?? 0));
+        if (targets.length === 0) {
+            continue;
+        }
+        qualifyingTargetCount += targets.length;
+        const maxReward = Math.max(0, ...programs.map(programMaximumReward));
+        const maxTargetScore = Math.max(0, ...targets.map((target) => readNumber(target.target_opportunity_score) ?? 0));
+        const balancedScore = repositoryHuntBalancedScore(maxReward, maxTargetScore, observedAt);
+        const formattedChange = formatRepositoryChange(change, input.output_mode);
+        const { programs: _eventPrograms, targets: _eventTargets, ...repositoryChange } = formattedChange;
+        rankedMatches.push({
+            balancedScore,
+            maxReward,
+            maxTargetScore,
+            observedAt,
+            payload: stripUndefined({
+                repository_change: repositoryChange,
+                programs,
+                targets: targets.slice(0, input.max_targets_per_result).map((target) => input.output_mode === "full" ? target : compactTarget(target)),
+                target_count: targets.length,
+                max_target_score: maxTargetScore,
+                max_program_reward: maxReward,
+                match_score: balancedScore,
+                why_ranked_here: repositoryHuntReasons(maxReward, maxTargetScore, observedAt)
+            })
+        });
+    }
+    rankedMatches.sort((left, right) => compareRepositoryHuntMatches(left, right, input.ranking_mode));
+    const matches = rankedMatches.slice(0, input.max_results).map((match, index) => ({
+        rank: index + 1,
+        ...match.payload
+    }));
+    const matchedPrograms = uniqueProgramsFromRepositoryMatches(matches);
+    const programWarnings = readArray(programPayload.warnings).filter((warning) => typeof warning === "string");
+    if (candidatePrograms.length === 0) {
+        warnings.push("No programs matched the reward and program-level filters. Relax one program filter and retry.");
+    }
+    else if (matches.length === 0) {
+        warnings.push("Programs matched, but no recent repository event also contained a target that passed the target-quality filters. Relax one target or freshness filter and retry.");
+    }
+    const programBudget = readObject(programPayload.upstream_budget);
+    const usedRequests = (readNumber(programBudget?.used) ?? 0) + repository.attempts;
+    return stripUndefined({
+        request_id: randomUUID(),
+        fetched_at: new Date().toISOString(),
+        source_requests: [
+            ...readArray(programPayload.source_requests),
+            {
+                source: "repository_changes",
+                request_id: repository.api.requestId,
+                upstream_request_id: repository.api.upstreamRequestId,
+                page: 1,
+                page_size: repository.pageSize,
+                ...apiSourceMetadata(repository.api)
+            }
+        ],
+        warnings: uniqueStrings([...programWarnings, ...warnings]),
+        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,
+            opportunity_levels: input.opportunity_levels.length > 0 ? input.opportunity_levels : undefined,
+            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,
+            changed_since: input.changed_since,
+            free_submission_only: input.free_submission_only,
+            min_target_score: input.min_target_score,
+            target_opportunity_labels: input.target_opportunity_labels.length > 0 ? input.target_opportunity_labels : undefined,
+            competition_risks: input.competition_risks.length > 0 ? input.competition_risks : undefined,
+            ranking_mode: input.ranking_mode,
+            output_mode: input.output_mode
+        }),
+        upstream_budget: {
+            initial: input.upstream_request_budget,
+            used: usedRequests,
+            remaining: Math.max(0, input.upstream_request_budget - usedRequests)
+        },
+        ranking_scope: readObject(programPayload.ranking_scope),
+        programs: matchedPrograms,
+        matches,
+        meta: {
+            returned: matches.length,
+            matched_programs: matchedPrograms.length,
+            program_candidates: candidatePrograms.length,
+            repository_events_scanned: readArray(readObject(repository.api.data)?.results).length,
+            qualifying_targets_before_result_limit: qualifyingTargetCount,
+            repository_page_size_used: repository.pageSize,
+            repository_request_attempts: repository.attempts,
+            parallel_source_fetch: true
+        }
+    });
+}
+async function fetchRepositoryHuntPage(client, input, warnings, maxAttempts) {
+    let pageSize = input.repository_page_size;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            const api = await client.getRepositoryChanges(toQuery({
+                include_targets: true,
+                platforms: input.platforms.length > 0 ? input.platforms : undefined,
+                tags: input.tags.length > 0 ? input.tags : undefined,
+                free_submission_only: input.free_submission_only,
+                include_removed: false,
+                include_ineligible: false,
+                include_out_of_scope: false,
+                page: 1,
+                page_size: pageSize
+            }));
+            return { api, pageSize, attempts: attempt };
+        }
+        catch (error) {
+            if (!(error instanceof BBRadarApiError) || error.status !== 413 || attempt >= maxAttempts || pageSize <= 10) {
+                throw error;
+            }
+            const reducedPageSize = Math.max(10, Math.floor(pageSize / 2));
+            warnings.push(`Repository page_size was reduced from ${pageSize} to ${reducedPageSize} after a 413 association-limit response.`);
+            pageSize = reducedPageSize;
+        }
+    }
+    throw new Error("No repository-change response was collected.");
+}
+function repositoryHuntTargetMatches(target, input) {
+    if (readBoolean(target.in_scope) !== true || readBoolean(target.eligible_for_bounty) !== true) {
+        return false;
+    }
+    const score = readNumber(target.target_opportunity_score);
+    if (score === undefined || score < input.min_target_score) {
+        return false;
+    }
+    if (input.target_opportunity_labels.length > 0 &&
+        !input.target_opportunity_labels.includes(stringField(target, "target_opportunity_label"))) {
+        return false;
+    }
+    if (input.competition_risks.length > 0 &&
+        !input.competition_risks.includes(stringField(target, "competition_risk"))) {
+        return false;
+    }
+    if (input.target_types.length > 0 && !input.target_types.some((targetType) => targetMatchesRequestedType(target, targetType))) {
+        return false;
+    }
+    if (input.scope_tags.length > 0 && !targetMatchesAnyTags(target, input.scope_tags, "scope_tags")) {
+        return false;
+    }
+    if (input.language_tags.length > 0 && !targetMatchesAnyTags(target, input.language_tags, "language_tags")) {
+        return false;
+    }
+    return true;
+}
+function targetMatchesAnyTags(target, requested, field) {
+    const actual = new Set(readStringArrayField(target, field).map(normalizeTag));
+    return requested.map(normalizeTag).some((value) => actual.has(value));
+}
+function programMaximumReward(program) {
+    return readNumber(readObject(program.reward_range)?.max) ?? 0;
+}
+function repositoryHuntBalancedScore(maxReward, maxTargetScore, observedAt) {
+    const rewardScore = Math.min(100, Math.log10(Math.max(1, maxReward)) / 7 * 100);
+    const ageDays = observedAt > 0 ? Math.max(0, Date.now() - observedAt) / (24 * 60 * 60 * 1000) : 30;
+    const freshnessScore = Math.max(0, 100 - Math.min(30, ageDays) / 30 * 100);
+    return Math.round((maxTargetScore * 0.45 + rewardScore * 0.35 + freshnessScore * 0.2) * 100) / 100;
+}
+function repositoryHuntReasons(maxReward, maxTargetScore, observedAt) {
+    const reasons = [`target score up to ${maxTargetScore}`, `maximum reward ${maxReward}`];
+    if (observedAt > 0) {
+        reasons.push(`repository activity observed ${new Date(observedAt).toISOString()}`);
+    }
+    return reasons;
+}
+function compareRepositoryHuntMatches(left, right, mode) {
+    if (mode === "highest_reward") {
+        return right.maxReward - left.maxReward || right.maxTargetScore - left.maxTargetScore || right.observedAt - left.observedAt;
+    }
+    if (mode === "best_target") {
+        return right.maxTargetScore - left.maxTargetScore || right.maxReward - left.maxReward || right.observedAt - left.observedAt;
+    }
+    if (mode === "newest") {
+        return right.observedAt - left.observedAt || right.maxTargetScore - left.maxTargetScore || right.maxReward - left.maxReward;
+    }
+    return right.balancedScore - left.balancedScore || right.observedAt - left.observedAt;
+}
+function uniqueProgramsFromRepositoryMatches(matches) {
+    const programs = new Map();
+    for (const match of matches) {
+        for (const value of readArray(match.programs)) {
+            const program = readObject(value);
+            const id = stringField(program, "id");
+            if (program && id && !programs.has(id)) {
+                programs.set(id, program);
+            }
+        }
+    }
+    return [...programs.values()];
+}
 async function findPrograms(client, config, input) {
     const normalized = normalizeFindProgramsInput(input);
     const warnings = normalized.warnings;