@bbradar/mcp 0.3.1 → 0.3.3

package/dist/server.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.1";
+const SERVER_VERSION = "0.3.3";
 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.31.0";
+const SDK_VERSION = "1.32.2";
 const CORE_TOOL_NAMES = new Set([
     "search_programs",
     "get_program",
@@ -294,7 +294,7 @@ const ACTIVITY_SHARED_PARAMS = ["tab", "sort", "direction", "platforms", "tags",
 // a request so it cannot be silently ignored or reinterpreted.
 const ACTIVITY_TAB_PARAMS = {
     payouts: ["period", "basis", "precision"],
-    value: ["include_map"],
+    value: ["period", "include_map"],
     scope: ["period"],
     rewards: ["period"],
     updates: ["period", "category"],
@@ -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 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 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, and an omitted direction for first_response or time_to_bounty means ascending (fastest first). 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()
@@ -348,6 +348,7 @@ const programIdSchema = z
     message: "program_id cannot contain control characters."
 })
     .describe("platform:handle id.");
+const PROGRAM_IDENTIFIER_DESCRIPTION = "BBRadar platform:handle program_id or a human program name/handle. Names are resolved automatically.";
 const programIdentifierSchema = z
     .string()
     .trim()
@@ -356,9 +357,9 @@ const programIdentifierSchema = z
     .refine((value) => !/[\u0000-\u001F\u007F]/.test(value), {
     message: "Program identifiers cannot contain control characters."
 })
-    .describe("BBRadar platform:handle program_id or a human program name/handle. Names are resolved automatically.");
+    .describe(PROGRAM_IDENTIFIER_DESCRIPTION);
 function jsonRecordSchema() {
-    return z.record(z.unknown());
+    return z.record(z.string(), z.unknown());
 }
 function programOutputSchema() {
     return jsonRecordSchema();
@@ -380,6 +381,13 @@ function apiEnvelopeOutputShape() {
         error: jsonRecordSchema().optional()
     };
 }
+// Tools that return one Pro API payload as it is. The API adds response fields
+// between MCP releases, and clients validate each structured result against the
+// discovered schema: listed fields document the contract, while a new top-level
+// field validates instead of failing every call (the API added Status facets on 2026-10-13).
+function apiMirrorOutput(shape) {
+    return z.object(shape).passthrough();
+}
 function programListOutputShape() {
     return {
         ...apiEnvelopeOutputShape(),
@@ -517,8 +525,8 @@ export function createBbradarServer(client, config) {
     const repositoryChangesPageSizeSchema = z.number().int().min(1).max(maxRepositoryChangesPageSize).default(Math.min(50, maxRepositoryChangesPageSize));
     const acceptedTargetLimitSchema = z.number().int().min(1).max(maxProgramTargetsPageSize);
     const targetSearchPageSizeSchema = z.number().int().min(1).max(maxTargetSearchPageSize).default(Math.min(50, maxTargetSearchPageSize));
-    const historyOutput = { ...apiEnvelopeOutputShape(), changes: z.array(jsonRecordSchema()).optional(), coverage: jsonRecordSchema().optional(), meta: jsonRecordSchema().optional() };
-    const analyticsOutput = { ...apiEnvelopeOutputShape(), platform: z.string().optional(), program: jsonRecordSchema().optional(), programs: z.array(jsonRecordSchema()).optional(), series: z.array(jsonRecordSchema()).optional(), observations: jsonRecordSchema().optional(), category: z.string().optional(), population: z.string().optional(), ranking_definition: z.string().optional(), inventory_definition: z.string().optional(), meta: jsonRecordSchema().optional() };
+    const historyOutput = apiMirrorOutput({ ...apiEnvelopeOutputShape(), changes: z.array(jsonRecordSchema()).optional(), coverage: jsonRecordSchema().optional(), meta: jsonRecordSchema().optional() });
+    const analyticsOutput = apiMirrorOutput({ ...apiEnvelopeOutputShape(), platform: z.string().optional(), program: jsonRecordSchema().optional(), programs: z.array(jsonRecordSchema()).optional(), series: z.array(jsonRecordSchema()).optional(), observations: jsonRecordSchema().optional(), category: z.string().optional(), population: z.string().optional(), ranking_definition: z.string().optional(), inventory_definition: z.string().optional(), meta: jsonRecordSchema().optional() });
     // Published Activity versions are 64 lowercase hex characters. "start" and
     // catalog snapshot tokens are different contracts and are rejected here.
     const activitySnapshotSchema = z.string().regex(/^[0-9a-f]{64}$/, "Use a snapshot_id returned by Activity.")
@@ -537,7 +545,7 @@ export function createBbradarServer(client, config) {
         program_type: z.enum(["paid", "vdp", "unknown"]).optional(),
         search: z.string().min(1).max(200).optional(),
         current_status: z.enum(["active", "paused", "suspended", "disabled", "closed", "unavailable", "unknown"]).optional(),
-        labels: z.array(z.string().min(1).max(64)).max(10).optional().describe("Only labels listed by get_activity_capabilities; others return 422."),
+        labels: z.array(z.string().min(1).max(64)).max(10).optional().describe("Only labels listed by get_activity_capabilities (for tab=value, the chosen period view's labels); others return 422."),
         opportunity_tiers: z.array(opportunityLevelSchema).min(1).max(4).optional().describe("Any of these catalog opportunity tiers, as frozen into the Activity version. get_activity_capabilities lists the tiers present in facets.opportunity_tiers; an API without the filter is rejected before any request."),
         launched_within: z.enum(["7d", "30d", "90d"]).optional(),
         category: z.enum(["scope", "rewards", "rules", "program"]).optional(),
@@ -547,19 +555,23 @@ export function createBbradarServer(client, config) {
         cursor: opaqueCursorSchema.optional(), limit: proLimitSchema.default(25),
         snapshot: activitySnapshotSchema.optional()
     };
-    const activityOutput = {
+    const activityOutput = apiMirrorOutput({
         ...apiEnvelopeOutputShape(), rows: z.array(jsonRecordSchema()).optional(), points: z.array(jsonRecordSchema()).optional(),
         tab: z.string().optional(), period: z.string().nullable().optional(),
         basis: z.string().nullable().optional(), precision: z.string().nullable().optional(),
         sort: z.string().nullable().optional(), direction: z.string().optional(), meta: jsonRecordSchema().optional(),
         cohort_median: jsonRecordSchema().nullable().optional(), available_views: z.array(jsonRecordSchema()).optional(),
-        map_points_omitted: z.number().int().optional()
-    };
+        map_points_omitted: z.number().int().optional(),
+        // tab=value: the label shortlist applied, including a default landing list (empty = the map's programs).
+        labels: z.array(z.string()).optional(),
+        // tab=status: event counts per change_type and current_status, each under the other filters.
+        facets: jsonRecordSchema().optional()
+    });
     registerTool("get_activity_capabilities", {
         title: "Get Available Activity Views",
         description: "Read the exact enabled period, sort, direction, basis and precision combinations before choosing an Activity ranking. Availability is evaluated before user filters; do not infer combinations from independent enums. Honor each view's sort_directions and default_direction and the enabled label list. The snapshot block identifies the published version these capabilities belong to.",
         inputSchema: z.object({ snapshot: activitySnapshotSchema.optional() }).strict(),
-        outputSchema: { ...apiEnvelopeOutputShape(), tabs: z.array(jsonRecordSchema()).optional(), version: z.union([z.string(), z.number()]).optional(), facets: jsonRecordSchema().optional(), labels: z.array(z.string()).optional(), listing: jsonRecordSchema().optional(), listing_payouts_enabled: z.boolean().optional(), derived_signals_enabled: z.boolean().optional(), snapshot: jsonRecordSchema().optional() },
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), tabs: z.array(jsonRecordSchema()).optional(), version: z.union([z.string(), z.number()]).optional(), facets: jsonRecordSchema().optional(), labels: z.array(z.string()).optional(), listing: jsonRecordSchema().optional(), listing_payouts_enabled: z.boolean().optional(), derived_signals_enabled: z.boolean().optional(), snapshot: jsonRecordSchema().optional() }),
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_activity_capabilities", config, rateLimiter, async () => {
         assertProFeature(client, "activity_capabilities", "enabled");
@@ -570,7 +582,7 @@ export function createBbradarServer(client, config) {
         title: "Get Current Activity Version",
         description: "Read only the identity of the currently published Activity version: snapshot_id, frozen as_of cutoff, expires_at, policy_version and suggested poll_seconds. Pass snapshot_id as snapshot only to get_activity_capabilities, get_activity_rankings and get_program_payouts. Catalog/feed tools such as find_programs use snapshot=start then meta.snapshot instead. as_of is when BBRadar froze its calculation, not a provider payment or update time.",
         inputSchema: z.object({}).strict(),
-        outputSchema: { ...apiEnvelopeOutputShape(), snapshot_id: z.string().optional(), as_of: z.string().optional(), expires_at: z.string().optional(), policy_version: z.string().optional(), poll_seconds: z.number().optional() },
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), snapshot_id: z.string().optional(), as_of: z.string().optional(), expires_at: z.string().optional(), policy_version: z.string().optional(), poll_seconds: z.number().optional() }),
         annotations: readOnlyAnnotations
     }, () => runTool("get_activity_snapshot", config, rateLimiter, async () => {
         assertProFeature(client, "activity_snapshot", "enabled");
@@ -583,11 +595,11 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("get_program_payouts", {
         title: "Get Program Payouts and Response Facts",
-        description: "Read reported totals, measured counter increases, source dates, precision, report and response facts, derived signals and label explanations for one exact platform:handle. Keep null separate from zero, bounds separate from exact amounts and unknown payment dates null. Payout timestamps are when increases were seen, never payment dates. No provider requests are made.",
+        description: "Read reported totals, measured counter increases, source dates, precision, report and response facts, derived signals and label explanations for one exact platform:handle. facts also carry each platform's own published figures (paid_average, paid_maximum, last_paid_on, HackerOne per-severity averages and report counts, triage/resolution times, response rate, researcher counts), each with its measure, unit, period and source_label; keep each definition and never compare them across platforms as one measure. Keep null separate from zero, bounds separate from exact amounts and unknown payment dates null. Payout timestamps are when increases were seen, never payment dates. value_points (include_map) are same-platform peers in the Value period named by value_period. No provider requests are made.",
         inputSchema: z.object({ program_id: programIdSchema, snapshot: activitySnapshotSchema.optional(), include_map: includeMapSchema }).strict(),
-        // Mirrors the API response, including its version identity: a client that
+        // Lists the API response fields, including its version identity: a client that
         // discovered this schema validates every structured result against it.
-        outputSchema: { ...apiEnvelopeOutputShape(), program_id: z.string().optional(), program: jsonRecordSchema().optional(), summary: jsonRecordSchema().optional(), as_of: z.string().optional(), snapshot_id: z.string().optional(), expires_at: z.string().nullable().optional(), facts: z.array(jsonRecordSchema()).optional(), windows: jsonRecordSchema().optional(), series: z.array(jsonRecordSchema()).optional(), payout_summary: jsonRecordSchema().nullable().optional(), views: z.array(jsonRecordSchema()).optional(), reports: jsonRecordSchema().optional(), response: jsonRecordSchema().optional(), last_increase_at: z.string().nullable().optional(), signals: jsonRecordSchema().optional(), label_details: z.array(jsonRecordSchema()).optional(), labels: z.array(z.string()).optional(), value_points: z.array(jsonRecordSchema()).optional(), map_points_omitted: z.number().int().optional(), meta: jsonRecordSchema().optional() },
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), program_id: z.string().optional(), program: jsonRecordSchema().optional(), summary: jsonRecordSchema().optional(), as_of: z.string().optional(), snapshot_id: z.string().optional(), expires_at: z.string().nullable().optional(), facts: z.array(jsonRecordSchema()).optional(), windows: jsonRecordSchema().optional(), series: z.array(jsonRecordSchema()).optional(), payout_summary: jsonRecordSchema().nullable().optional(), views: z.array(jsonRecordSchema()).optional(), reports: jsonRecordSchema().optional(), response: jsonRecordSchema().optional(), last_increase_at: z.string().nullable().optional(), signals: jsonRecordSchema().optional(), label_details: z.array(jsonRecordSchema()).optional(), labels: z.array(z.string()).optional(), value_points: z.array(jsonRecordSchema()).optional(), value_period: z.string().nullable().optional(), map_points_omitted: z.number().int().optional(), meta: jsonRecordSchema().optional() }),
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_program_payouts", config, rateLimiter, async () => {
         assertProFeature(client, "program_payouts", "enabled");
@@ -606,7 +618,7 @@ export function createBbradarServer(client, config) {
     };
     registerTool("get_activity_rankings", {
         title: "Get Activity Ranking",
-        description: "One globally ranked server page of an Activity view, frozen at meta.as_of. Read get_activity_capabilities first: explicit period/basis/precision/sort/direction never fall back, and each tab only accepts its own inputs. tab: payouts (reported and tracked bases stay separate; proven_bounds desc = highest reported minimum, asc = lowest reported maximum, never an exact ranking; source totals can lag); value (fixed lifetime generosity and 90-day volume percentiles, no period; one label gives its shortlist); scope (recorded additions/removals/net, not inventory differences); rewards (net reward-range change, unknown % stays null); updates (active UTC days, change groups); reports (received counts; volume is not competition; all_time is the lifetime counter); response (resolved counts, last resolution, response time; time to bounty is award timing); status (first_seen/paused/resumed/left_listing/returned events); all_changes (chronological events; get_activity_change_detail for before/after). Event tabs use rolling 7d/30d/90d, not calendar months. launched_within applies to reports/response. Payout increases are observed counters, not payment dates. Reuse cursors only with identical inputs. For several signals at once, or with Web2/scope/competition/fee filters, use find_programs or find_hunt_targets.",
+        description: "One globally ranked server page of an Activity view, frozen at meta.as_of. Read get_activity_capabilities first: explicit period/basis/precision/sort/direction never fall back, and each tab only accepts its own inputs. tab: payouts (reported and tracked bases stay separate; proven_bounds desc = highest reported minimum, asc = lowest reported maximum, never an exact ranking; source totals can lag; average_paid is the platform's own current average payment, a range for HackerOne); value (advertised period 7d/30d/90d of report volume against lifetime payout per processed report; each row's value holds that period's count and percentile; Pays near top, No payouts seen and processed_received are 90d only; without period, labels or sort mean 90d and a bare read opens the advertised default, whose shortlist the page's labels name; one label gives its shortlist); scope (recorded additions/removals/net, not inventory differences); rewards (net reward-range change comparing native maxima, unknown % stays null; minimum_usd/maximum_usd are display conversions); updates (active UTC days, change groups); reports (received counts; volume is not competition; all_time is the lifetime counter); response (resolved counts, last resolution, response time with each provider's own label and window; time to bounty is award timing; durations default to fastest first); status (first_seen/paused/resumed/left_listing/returned events; facets count events per change_type and current_status); all_changes (chronological events; get_activity_change_detail for before/after). Event tabs use rolling 7d/30d/90d, not calendar months. launched_within applies to reports/response. Payout increases are observed counters, not payment dates. Reuse cursors only with identical inputs. For several signals at once, or with Web2/scope/competition/fee filters, use find_programs or find_hunt_targets.",
         inputSchema: z.object(activityParams).strict(),
         outputSchema: activityOutput,
         annotations: readOnlyAnnotations
@@ -617,14 +629,14 @@ export function createBbradarServer(client, config) {
     // Single-view aliases for the full profile; each schema exposes only the
     // inputs its view accepts and shares the ranking tool's request path.
     const activityDescriptions = {
-        value: "Discover programs with frozen within-platform value and report-volume percentiles. Generosity is lifetime; volume is 90 days. No period or launch-cohort input applies. Use a label-specific shortlist: Pays near top orders by realization, No payouts seen by received_90d (raw count with its basis; small cohorts remain eligible). Comparative ratio sorts use server percentiles; never recompute after filtering. Preserve label_details explanations and destinations. A counter increase is observed activity, not an individual payment. Map points are returned only with include_map.",
-        payouts: "Rank payouts using the same server calculation as BBRadar. Last 7 days and last 30 days are rolling windows. Explicit periods never fall back. For high or low payouts lately, use the same enabled tracked-30-day cohort, or separately label a native-90-day cohort. Reported and tracked bases stay separate. With proven_bounds, descending is Highest reported minimum using lower bounds; ascending is Lowest reported maximum using upper bounds. Neither claims an exact ranking. Source totals can be delayed, including Immunefi.",
+        value: "Discover programs with frozen within-platform value and report-volume percentiles. Generosity is lifetime payout per processed report; volume covers the selected period: 7d, 30d or 90d, each only when get_activity_capabilities advertises it. Each row's value holds that period's received count, basis and percentile; signals keep the lifetime and 90-day figures. Without period, naming labels or sort means 90d, and a bare read opens the advertised default, which may be a shortlist named in the page's labels. No launch-cohort input applies. High value, Popular and Low per report exist per period; Pays near top (orders by realization), No payouts seen (orders by received_90d, raw count with its basis; small cohorts remain eligible) and processed_received are 90d only. Comparative ratio sorts use server percentiles; never recompute after filtering. Preserve label_details explanations and destinations. A counter increase is observed activity, not an individual payment. Map points are returned only with include_map.",
+        payouts: "Rank payouts using the same server calculation as BBRadar. Last 7 days and last 30 days are rolling windows. Explicit periods never fall back. For high or low payouts lately, use the same enabled tracked-30-day cohort, or separately label a native-90-day cohort. Reported and tracked bases stay separate. With proven_bounds, descending is Highest reported minimum using lower bounds; ascending is Lowest reported maximum using upper bounds. Neither claims an exact ranking. Source totals can be delayed, including Immunefi. Rows also carry average_paid, the platform's own current average payment with its source_label, period, native currency and USD conversion (HackerOne publishes a 45th-55th percentile range); it is the same in every period, and sort=average_paid ranks it where advertised.",
         scope: "Rank recorded scope additions, removals, net movement or largest update; not differences between inventory totals. Periods are rolling 7, 30 or 90 days, not calendar months.",
-        rewards: "Rank comparable net reward-range changes over rolling 7, 30 or 90 days. Unknown change percentages remain null.",
+        rewards: "Rank comparable net reward-range changes over rolling 7, 30 or 90 days. The change percentage compares native maxima; unknown percentages remain null. before/after keep native amounts and add minimum_usd/maximum_usd at the version's current quotes for display (null without a quote).",
         updates: "Rank active UTC days and recorded change groups over rolling periods. Baselines and internal corrections are excluded.",
         reports: "Rank received report counts. Each program uses measured lifetime-counter growth where available, otherwise its supported native period. All-time is the current lifetime counter. Previous and change compare like-for-like. Report volume is not competition. Launch cohorts use the canonical launch date; amounts are not reports since launch.",
-        response: "Rank resolved counter growth or current lifetime counters, last resolution, response duration or time to bounty. Keep the provider's definition: time to bounty is award timing, not payment settlement. Period applies only to resolved counts.",
-        status: "Read distinct First seen, Paused, Resumed, Left listing and Returned events. Event type and current status are separate filters; never merge events from one program.",
+        response: "Rank resolved counter growth or current lifetime counters, last resolution, response duration or time to bounty. Each cell keeps its provider's definition, label and window (for example HackerOne first response over 90 days, YesWeHack's 6-month band, Bugcrowd's 75% validated time); first_response_precision says whether a time is exact, a band bound or approximate. Time to bounty is award timing, not payment settlement. Durations sort fastest first unless a direction is given. Period applies only to resolved counts; use only advertised periods.",
+        status: "Read distinct First seen, Paused, Resumed, Left listing and Returned events. Event type and current status are separate filters; never merge events from one program. facets count events per change_type and current_status for the period and filters, each counted without its own selection; offer only options with counts.",
         all_changes: "Read chronological semantic program changes with event IDs. Fetch get_activity_change_detail lazily for before/after items, including eligible events for programs that left the catalog. Separate events stay separate."
     };
     for (const tab of ACTIVITY_TABS) {
@@ -643,7 +655,7 @@ export function createBbradarServer(client, config) {
         title: "Get Activity Change Detail",
         description: "Read one bounded page of recorded before/after items for an exact Activity event ID in its source snapshot. Pass meta.snapshot_id from the Activity page. Retained eligible events may describe programs that have left the catalog. Reuse an opaque cursor only with the same event, snapshot and limit.",
         inputSchema: z.object({ event_id: z.string().min(1).max(128), snapshot: activitySnapshotSchema.describe("meta.snapshot_id from the Activity page that supplied this event."), cursor: opaqueCursorSchema.optional(), limit: proLimitSchema.default(50) }).strict(),
-        outputSchema: { ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }, annotations: readOnlyAnnotations
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }), annotations: readOnlyAnnotations
     }, (args) => runTool("get_activity_change_detail", config, rateLimiter, async () => {
         assertProFeature(client, "activity_event_detail", "enabled");
         return proPage(await client.getActivityChangeDetail(args.event_id, toQuery({ snapshot: args.snapshot, cursor: args.cursor, limit: args.limit })), "items");
@@ -668,7 +680,7 @@ export function createBbradarServer(client, config) {
         title: "Get History Change Detail",
         description: "Fetch one semantic History change's paginated before/after items only when needed.",
         inputSchema: { change_id: z.string().min(1).max(128), cursor: opaqueCursorSchema.optional(), limit: proLimitSchema.default(50) },
-        outputSchema: { ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }, annotations: readOnlyAnnotations
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), change: jsonRecordSchema().optional(), items: z.array(jsonRecordSchema()).optional(), meta: jsonRecordSchema().optional() }), annotations: readOnlyAnnotations
     }, (args) => runTool("get_history_change_detail", config, rateLimiter, async () => {
         assertProFeature(client, "history_change_detail");
         assertHistoryCapture(client);
@@ -688,7 +700,7 @@ export function createBbradarServer(client, config) {
         title: "Get Exact Program Activity",
         description: "Read the authoritative activity_summary for one exact program ID.",
         inputSchema: { program_id: programIdSchema },
-        outputSchema: { ...apiEnvelopeOutputShape(), program_id: z.string().optional(), activity_summary: jsonRecordSchema().optional() }, annotations: readOnlyAnnotations
+        outputSchema: apiMirrorOutput({ ...apiEnvelopeOutputShape(), program_id: z.string().optional(), activity_summary: jsonRecordSchema().optional() }), annotations: readOnlyAnnotations
     }, (args) => runTool("get_program_activity", config, rateLimiter, async () => {
         assertProFeature(client, "program_activity");
         return proPage(await client.getProgramActivity(args.program_id), "activity_summary");
@@ -795,7 +807,7 @@ export function createBbradarServer(client, config) {
     }));
     registerTool("get_program", {
         title: "Get BBRadar Program",
-        description: "Get one program by platform:handle program_id, handle, or human program name. Names are resolved automatically when unambiguous.",
+        description: "Get one program by platform:handle program_id, handle, or human program name. Names are resolved automatically when unambiguous. A contest or Huntr challenge adds contest_awards: its final published award allocations (awarded_total and pool_amount as decimal strings in the contest's own currency token; currency null when the platform names none, as Huntr; never USD or a payment record), or null before a final result. A finished contest with a final result stays readable here by exact platform:handle, without an opportunity tag, although discovery and name resolution exclude ended contests.",
         inputSchema: {
             program_id: programIdentifierSchema
         },
@@ -1440,7 +1452,8 @@ export function createBbradarServer(client, config) {
             min_added_7d: z.number().int().min(0).optional(),
             max_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
             max_results: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(10),
-            sort_by: z.union([programSortSchema.removeDefault(), activityCatalogSortSchema]).optional(),
+            // One flat enum, as clients have always seen it; a union would advertise anyOf.
+            sort_by: z.enum([...programSortSchema.removeDefault().options, ...activityCatalogSortSchema.options]).optional(),
             include_target_samples: z.boolean().default(false),
             target_sample_programs: z.number().int().min(0).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
             target_sample_size: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(5),
@@ -2398,6 +2411,7 @@ function bbradarGuide(topic, profile, client) {
         { user_goal: "program payouts, recent reports, response times or Activity rankings", first_tool: "get_activity_capabilities", arguments: {}, then: "Choose an enabled period, sort and direction, then call get_activity_rankings with that tab for one server-ranked page. Do not approximate by paging or re-ranking the catalog." },
         { user_goal: "programs with recent payouts and new scope that also match Web2, competition or fee criteria", first_tool: "find_hunt_targets", arguments: { payout_period: "30d", payout_positive: true, scope_period: "30d", scope_added_min: 1, surface_mode: "web2", free_submission_only: true, ranking_mode: "lowest_competition" }, then: "Use find_programs with the same Activity inputs and competition_risks for program-only results; continue with scan.next_cursor." },
         { user_goal: "payout and report facts for one exact program", first_tool: "get_program_payouts", arguments: { program_id: "Platform:handle" } },
+        { user_goal: "final award results of a finished contest or Huntr challenge", first_tool: "get_program", arguments: { program_id: "Platform:handle" }, then: "Read contest_awards: awarded_total and pool_amount are decimal strings in the contest's own token (currency null when the platform names none); null means no final result yet." },
         { user_goal: "semantic program change history", first_tool: "get_program_history", arguments: { program_id: "Platform:handle" }, then: "Fetch get_history_change_detail only for a selected change." },
         { user_goal: "most active programs in a date range", first_tool: "get_analytics_program_activity", arguments: {}, then: "Use this server-side ranking rather than sampling the program catalog." },
         { user_goal: "exact recorded activity for one program", first_tool: "get_program_activity", arguments: { program_id: "Platform:handle" } },
@@ -2547,6 +2561,7 @@ function coreBbradarGuide(topic, client) {
         { user_goal: "program payouts, recent reports, response times or Activity rankings", first_tool: "get_activity_capabilities", arguments: {}, then: "Read supported view combinations and call get_activity_rankings with that tab. Use get_activity_change_detail lazily for a selected Activity event." },
         { user_goal: "programs with recent payouts and new scope that also match Web2, competition or fee criteria", first_tool: "find_hunt_targets", arguments: { payout_period: "30d", payout_positive: true, scope_period: "30d", scope_added_min: 1, surface_mode: "web2", free_submission_only: true, ranking_mode: "lowest_competition" } },
         { user_goal: "payout and report facts for one exact program", first_tool: "get_program_payouts", arguments: { program_id: "Platform:handle" } },
+        { user_goal: "final award results of a finished contest or Huntr challenge", first_tool: "get_program", arguments: { program_id: "Platform:handle" }, then: "Read contest_awards in the contest's own token; null means no final result yet." },
         { user_goal: "semantic program change history", first_tool: "get_program_history", arguments: { program_id: "Platform:handle" }, then: "Fetch change detail only when needed." },
         { user_goal: "most active programs", first_tool: "get_analytics_program_activity", arguments: {} },
         { user_goal: "exact recorded activity", first_tool: "get_program_activity", arguments: { program_id: "Platform:handle" } },
@@ -2818,7 +2833,7 @@ async function runProgramIdTool(client, config, requestedProgramId, callback, in
             return withProgramIdFallbackMetadata(payload, cachedFallback);
         }
         catch (cachedFallbackError) {
-            if (!isProgramNotFoundError(cachedFallbackError) || !indexFallbackCallback) {
+            if (!allowsProgramIdFallback(cachedFallbackError) || !indexFallbackCallback) {
                 throw cachedFallbackError;
             }
             const indexFallback = createProgramIndexFallbackFromStaleResolution(cachedFallback, requestedProgramId, cachedFallbackError) ??
@@ -2840,7 +2855,7 @@ async function runProgramIdTool(client, config, requestedProgramId, callback, in
                 return withProgramIdFallbackMetadata(payload, fallback);
             }
             catch (fallbackError) {
-                if (!isProgramNotFoundError(fallbackError) || !indexFallbackCallback) {
+                if (!allowsProgramIdFallback(fallbackError) || !indexFallbackCallback) {
                     throw fallbackError;
                 }
                 const indexFallback = createProgramIndexFallbackFromStaleResolution(fallback, requestedProgramId, fallbackError) ??
@@ -2868,7 +2883,7 @@ async function runProgramIdTool(client, config, requestedProgramId, callback, in
         return await callback(requestedProgramId);
     }
     catch (error) {
-        if (!isProgramNotFoundError(error)) {
+        if (!allowsProgramIdFallback(error)) {
             throw error;
         }
         const fallback = await resolveStaleProgramId(client, config, requestedProgramId, error);
@@ -2890,7 +2905,7 @@ async function runProgramIdTool(client, config, requestedProgramId, callback, in
             return withProgramIdFallbackMetadata(payload, fallback);
         }
         catch (fallbackError) {
-            if (!isProgramNotFoundError(fallbackError) || !indexFallbackCallback) {
+            if (!allowsProgramIdFallback(fallbackError) || !indexFallbackCallback) {
                 throw fallbackError;
             }
             const indexFallback = createProgramIndexFallbackFromStaleResolution(fallback, requestedProgramId, fallbackError) ??
@@ -5142,7 +5157,20 @@ async function getProgramFromTargetsOnlyFallback(client, programId, programError
 async function fetchProgramDetailsAndTargets(client, config, programId) {
     const [programResult, targetsResult] = await Promise.allSettled([client.getProgram(programId), client.getProgramTargets(programId)]);
     if (targetsResult.status === "rejected") {
-        throw targetsResult.reason;
+        const reason = targetsResult.reason;
+        if (programResult.status === "fulfilled" && isProgramNotFoundError(reason)) {
+            // Detail confirmed this exact program; only its target list is unavailable.
+            throw new ConfirmedProgramTargetsError({
+                message: `${programId} exists, but its target list is not available (${reason.message}). A finished contest keeps program detail only: read it with get_program.`,
+                requestId: reason.requestId,
+                upstreamRequestId: reason.upstreamRequestId,
+                status: reason.status,
+                detail: reason.detail,
+                errors: reason.errors,
+                cause: reason
+            });
+        }
+        throw reason;
     }
     const targetsApi = targetsResult.value;
     const targetSourceRequest = {
@@ -6292,6 +6320,7 @@ function compactProgram(program) {
         competition_risk: stringField(program, "competition_risk"),
         competition_risk_reason: stringField(program, "competition_risk_reason"),
         submission_cost: program.submission_cost,
+        contest_awards: program.contest_awards,
         payout_summary: program.payout_summary,
         activity: program.activity,
         activity_summary: program.activity_summary,
@@ -7825,6 +7854,17 @@ function serverCatalogQuery(client, input) {
             vdp_mode: input.vdp_mode, snapshot: input.snapshot }
     };
 }
+// Durations rank fastest first when no direction is given, as the API does. The
+// direction the server reports it applied wins, so an older API is labelled
+// correctly too.
+const ASCENDING_FIRST_SORTS = new Set(["first_response", "time_to_bounty"]);
+function appliedSortDirection(input, served) {
+    if (served === "asc" || served === "desc")
+        return served;
+    if (input.sort_direction === "asc" || input.sort_direction === "desc")
+        return input.sort_direction;
+    return ASCENDING_FIRST_SORTS.has(String(input.sort_by ?? "updated")) ? "asc" : "desc";
+}
 function readServerCatalogPage(client, catalog, page, pageSize, snapshot) {
     const query = toQuery({ ...catalog.query, snapshot, page, page_size: pageSize });
     return catalog.level ? client.getOpportunities(catalog.level, query) : client.listPrograms(query);
@@ -7841,7 +7881,7 @@ async function findServerCatalogPrograms(client, config, input) {
     const mode = input.output_mode === "full" ? "full" : "compact";
     return withApiMetadata(api, {
         programs: readArray(data?.programs).map((program) => formatProgram(sanitizeProgram(program, config.webBaseUrl), mode)),
-        ranking_scope: { mode: "server", sort_by: input.sort_by ?? "updated", sort_direction: input.sort_direction ?? "desc" },
+        ranking_scope: { mode: "server", sort_by: input.sort_by ?? "updated", sort_direction: appliedSortDirection(input, readObject(data?.meta)?.sort_direction) },
         meta: sanitizeJson(data?.meta)
     });
 }
@@ -7894,6 +7934,7 @@ async function scanServerCatalog(client, config, input, local, limits) {
     let token = start.t ?? input.snapshot;
     let totalPages;
     let serverTotal;
+    let servedDirection;
     let rowsScanned = 0;
     let pagesRead = 0;
     let restarted = false;
@@ -7952,6 +7993,7 @@ async function scanServerCatalog(client, config, input, local, limits) {
             version ??= pageVersion;
             totalPages = readNumber(meta?.total_pages) ?? totalPages;
             serverTotal = readNumber(meta?.total) ?? serverTotal;
+            servedDirection = meta?.sort_direction ?? servedDirection;
             if (token !== undefined && typeof meta?.snapshot === "string")
                 token = meta.snapshot;
             const rows = readArray(data?.programs);
@@ -7987,7 +8029,7 @@ async function scanServerCatalog(client, config, input, local, limits) {
         scan: stripUndefined({
             order: "Server order; local filters only remove programs.",
             sort_by: input.sort_by ?? "updated",
-            sort_direction: input.sort_direction ?? "desc",
+            sort_direction: appliedSortDirection(input, servedDirection),
             local_filters: localFilters.length > 0 ? localFilters : undefined,
             server_matches: serverTotal,
             rows_scanned: rowsScanned,
@@ -8906,6 +8948,16 @@ function addUniqueWarning(warnings, warning) {
 function isProgramNotFoundError(error) {
     return error instanceof BBRadarApiError && error.status === 404;
 }
+/**
+ * A target read failed for a program whose exact detail read succeeded. Detail confirmed
+ * the identity, so the failure belongs to that program's targets (a finished contest keeps
+ * detail only) and never makes its ID a stale-ID candidate for a same-handle program.
+ */
+class ConfirmedProgramTargetsError extends BBRadarApiError {
+}
+function allowsProgramIdFallback(error) {
+    return isProgramNotFoundError(error) && !(error instanceof ConfirmedProgramTargetsError);
+}
 function runImmediately(callback) {
     return callback();
 }
@@ -9055,7 +9107,9 @@ Summarize the program scope:
         title: "Prepare Passive Recon Plan",
         description: "Create a passive-only plan from BBRadar program and target data. Use only when planning is explicitly requested.",
         argsSchema: {
-            program_id: programIdentifierSchema.optional(),
+            // Zod 4 keeps a description on the schema it was set on, and prompt
+            // arguments read the outer optional, so describe it again here.
+            program_id: programIdentifierSchema.optional().describe(PROGRAM_IDENTIFIER_DESCRIPTION),
             focus: z.string().optional().describe("Optional focus area such as APIs, domains, mobile, or cloud.")
         }
     }, (args) => promptResult(`Prepare a passive-only plan from BBRadar data. Program id JSON string, if present: ${promptJson(args.program_id ?? "")}.