@bbradar/mcp 0.3.0 → 0.3.1

package/dist/server.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { requiresActivityQuery } from "./activityContract.js";
+import { requiresActivityQuery, validateActivityCatalogInput } from "./activityContract.js";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BBRadarApiError } from "./bbradarClient.js";
@@ -7,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.3.0";
+const SERVER_VERSION = "0.3.1";
 const MAX_PROGRAMS_PER_SEARCH = 100;
 const MAX_TARGET_EXPORT = 500;
 const MAX_RECENT_CHANGES = 100;
@@ -46,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",
@@ -257,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);
@@ -309,7 +309,7 @@ const activityEventPeriodSchema = () => z.enum(["7d", "30d", "90d"]);
 const activityCatalogNumberSchema = () => z.number().finite().min(0).optional();
 const activityCatalogInput = {
     program_type: z.enum(["paid", "vdp", "unknown"]).optional(),
-    payout_metric: z.enum(["payout_total", "payout_increase", "payout_native_90d"]).optional(),
+    payout_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(),
@@ -322,7 +322,7 @@ const activityCatalogInput = {
     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(),
+    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(),
@@ -336,7 +336,7 @@ const activityCatalogInput = {
     activity_labels: z.array(z.string().min(1).max(64)).max(10).optional(),
     sort_by: activityCatalogSortSchema.optional(), sort_direction: z.enum(["asc", "desc"]).optional()
 };
-const activityCatalogGuidance = "Give each Activity signal its period (e.g. payout_period=30d with payout_positive=true; scope_period with scope_added_min) and use sort_by/sort_direction combinations enabled in get_activity_capabilities; default is updated descending. Tracked no_increase/lower require 30d. Nothing falls back to another period or precision.";
+const 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()
@@ -444,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))) {
@@ -462,7 +468,8 @@ export function createBbradarServer(client, config) {
             "Use find_hunt_targets once for requests combining good rewards, broad scope, target quality, and recent target additions. Use find_repository_hunt_targets instead when Git or repository activity is explicitly required.",
             "Use find_programs for lower-level program-only discovery and find_programs_by_target for reverse target lookup.",
             "For payouts, reports, response measures or Activity comparisons, first read get_activity_capabilities, then get_activity_rankings with the matching tab for one ranking. For several conditions at once (e.g. recent payouts plus new scope, Web2-only, low competition, no submission fee) use one find_hunt_targets or find_programs call with Activity inputs and local filters together. Keep periods explicit; never intersect separately paginated rankings.",
-            "Activity data is published in versions. get_activity_snapshot reports the current version; pass its snapshot_id as snapshot to bind capabilities and first pages to one version, and never mix rows from different versions.",
+            "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."
@@ -474,7 +481,8 @@ export function createBbradarServer(client, config) {
             "Do not repeat program discovery with alternate sorts or fan out get_program_targets across a shortlist; find_hunt_targets already includes exact bounded samples and recent target additions.",
             "Use advanced tools only after the user's goal is clear or the guide points to them.",
             "For payouts, reports, response measures or Activity comparisons, first read get_activity_capabilities. Use get_activity_rankings (or its per-view alias) for one ranking, or one find_hunt_targets/find_programs call combining Activity inputs with Web2, scope, competition and fee filters. Keep server order and explicit periods; never re-rank a sampled catalog or intersect separate pages.",
-            "Activity data is published in versions. get_activity_snapshot reports the current version; pass its snapshot_id as snapshot to bind capabilities and first pages to one version, and never mix rows from different versions.",
+            "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.",
@@ -560,7 +568,7 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("get_activity_snapshot", {
         title: "Get Current Activity Version",
-        description: "Read only the identity of the currently published Activity version: snapshot_id, frozen as_of cutoff, expires_at, policy_version and suggested poll_seconds. Use it to detect newer Activity data and pass snapshot_id as snapshot to bind capabilities, first pages and payouts to one version. as_of is when BBRadar froze its calculation, not a provider payment or update time.",
+        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
@@ -918,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(),
@@ -1195,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),
@@ -2502,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
     };
@@ -2580,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) {
@@ -3590,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,
@@ -4738,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,
@@ -4770,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
         })
     });
 }
@@ -4818,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 {
@@ -4840,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;
@@ -4862,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,
@@ -4872,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,
@@ -4885,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,
@@ -4901,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
@@ -4933,6 +4939,7 @@ async function fetchProgramTargetsWithEndpointFallback(client, programId) {
             })),
             source: "program_targets",
             rawTargets,
+            coverage: targetPageCoverage(data, rawTargets.length, rawTargets.length),
             sourceRequests: [
                 {
                     source: "program_targets",
@@ -5032,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,
@@ -5053,6 +5067,7 @@ async function fetchProgramTargetsFromExportFallback(client, programId) {
             })),
             source: "target_export",
             rawTargets,
+            coverage,
             sourceRequests: [
                 {
                     source: "target_export",
@@ -5313,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",
@@ -5339,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,
@@ -5376,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",
@@ -5385,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, {
@@ -5411,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,
@@ -6820,6 +6857,18 @@ function clampLimit(name, value, max, warnings) {
 // 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);
@@ -6885,22 +6934,28 @@ async function findHuntTargets(client, config, input, activity = {}) {
         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([
-        serverFiltered
+        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)
-            : findPrograms(client, config, programInput),
+            }, 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;
@@ -6919,8 +6974,12 @@ async function findHuntTargets(client, config, input, activity = {}) {
     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.`);
     }
@@ -6934,6 +6993,10 @@ async function findHuntTargets(client, config, input, activity = {}) {
     }));
     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(),
@@ -6985,7 +7048,10 @@ async function findHuntTargets(client, config, input, activity = {}) {
         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: {
@@ -6998,7 +7064,8 @@ async function findHuntTargets(client, config, input, activity = {}) {
             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
         }
     });
 }
@@ -7738,6 +7805,7 @@ function hasActivityCatalogInput(input) {
 }
 /** 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.");
@@ -7817,6 +7885,7 @@ async function scanServerCatalog(client, config, input, local, limits) {
     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;
@@ -7840,11 +7909,25 @@ async function scanServerCatalog(client, config, input, local, limits) {
         const needed = pagesRead === 0 ? 1 : Math.ceil((limits.maxResults - matches.length) / (rate * pageSize));
         const batch = Math.max(1, Math.min(allowance, needed, CATALOG_SCAN_PREFETCH));
         const pageToken = token;
-        const pages = await Promise.all(Array.from({ length: batch }, (_, index) => nextPage + index)
+        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) })));
-        for (const { page, api } of pages) {
+        // 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;
-            limits.budget.remaining -= api.cached || api.coalesced ? 0 : 1;
             sourceRequests.push({ source: catalog.level ? `opportunities:${catalog.level}` : "programs", page, request_id: api.requestId,
                 upstream_request_id: api.upstreamRequestId, ...apiSourceMetadata(api) });
             const data = readObject(api.data);
@@ -7900,6 +7983,7 @@ async function scanServerCatalog(client, config, input, local, limits) {
     return {
         candidates: matches,
         sourceRequests,
+        errors,
         scan: stripUndefined({
             order: "Server order; local filters only remove programs.",
             sort_by: input.sort_by ?? "updated",
@@ -7913,17 +7997,20 @@ async function scanServerCatalog(client, config, input, local, limits) {
                 ? 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
+            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) {
+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 });
+    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.");
     }
@@ -7936,6 +8023,7 @@ async function findFilteredServerPrograms(client, config, input, local, maxResul
         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 },
@@ -7950,10 +8038,11 @@ function programHasNoSubmissionFee(program) {
     const amount = numberField(cost, "amount");
     return amount === undefined || (amount === 0 && (numberField(cost, "maximum_amount") ?? 0) === 0);
 }
-async function findPrograms(client, config, input) {
+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
@@ -7970,11 +8059,13 @@ async function findPrograms(client, config, input) {
         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))
@@ -7998,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,
@@ -8040,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: {
@@ -8445,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);
@@ -9280,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,
@@ -9291,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
     }));
 }