@bbradar/mcp 0.1.7 → 0.1.10

package/dist/server.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { BBRadarApiError } from "./bbradarClient.js";
-import { stripUndefined } from "./json.js";
+import { stableStringify, stripUndefined } from "./json.js";
 import { FixedWindowRateLimiter } from "./rateLimit.js";
 import { readArray, readBoolean, readNumber, readObject, readString, sanitizeJson, sanitizeChange, sanitizeProgram, sanitizeTarget, sanitizeTargetsForExport } from "./sanitize.js";
 const SERVER_VERSION = "0.1.0";
@@ -29,8 +29,9 @@ const DEFAULT_FILTER_TARGET_SAMPLE_PROGRAMS = 10;
 const MAX_FILTER_TARGET_SAMPLE_PROGRAMS = 25;
 const MAX_LOCAL_EXPORT_RESOURCES = 25;
 const EXPORT_PREVIEW_LIMIT = 25;
-const STALE_PROGRAM_ID_RESOLVE_PAGES = 5;
-const STALE_PROGRAM_ID_RESOLVE_BUDGET = 5;
+const STALE_PROGRAM_ID_RESOLVE_PAGES = 1;
+const STALE_PROGRAM_ID_RESOLVE_BUDGET = 1;
+const PROGRAM_FALLBACK_CACHE_MAX_ENTRIES = 200;
 const MAX_RESOLVE_SEARCH_QUERIES = 4;
 const SDK_VERSION = "1.29.0";
 const WEB3_TAGS = ["web3", "crypto", "blockchain", "smart-contract", "smart contract", "defi", "nft", "ethereum", "solana", "solidity"];
@@ -275,10 +276,18 @@ export function createBbradarServer(client, config) {
         annotations: readOnlyAnnotations
     }, (args) => runTool("get_program", config, rateLimiter, async () => {
         return runProgramIdTool(client, config, args.program_id, async (programId) => {
-            const api = await client.getProgram(programId);
-            return withApiMetadata(api, {
-                program: addProgramResourceLinks(sanitizeProgram(api.data, config.webBaseUrl))
-            });
+            try {
+                const api = await client.getProgram(programId);
+                return withApiMetadata(api, {
+                    program: addProgramResourceLinks(sanitizeProgram(api.data, config.webBaseUrl))
+                });
+            }
+            catch (error) {
+                if (!isProgramNotFoundError(error)) {
+                    throw error;
+                }
+                return getProgramFromTargetsOnlyFallback(client, programId, error);
+            }
         }, async (indexFallback) => ({
             request_id: randomUUID(),
             warnings: [`Returned program metadata from the BBRadar program index because the per-program detail endpoint returned 404 for ${indexFallback.resolvedProgramId}.`],
@@ -347,9 +356,40 @@ export function createBbradarServer(client, config) {
         },
         annotations: readOnlyAnnotations
     }, (args) => runTool("run_program_name_action", config, rateLimiter, async () => runProgramNameAction(client, config, args)));
+    server.registerTool("get_program_eligible_targets_by_name", {
+        title: "Get Eligible Targets By Program Name",
+        description: "Fast one-call path for user asks like 'find in-scope eligible targets for Aztec': resolve the program name, fetch targets, and return filtered in-scope bounty-eligible targets. Prefer this over separate resolve_program + get_program_targets calls when the user asks for a target list by name.",
+        inputSchema: {
+            query: searchTextSchema,
+            platforms: stringListSchema,
+            tags: stringListSchema,
+            opportunity_levels: z.array(opportunityLevelSchema).max(4).default([]),
+            max_resolve_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
+            upstream_request_budget: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(DEFAULT_FIND_UPSTREAM_REQUEST_BUDGET),
+            include_out_of_scope: z.boolean().default(false),
+            include_ineligible: z.boolean().default(false),
+            strict_scope_filter: z.boolean().default(true),
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().min(1).max(MAX_TARGETS_PER_PROGRAM).default(MAX_TARGETS_PER_PROGRAM),
+            target_list_mode: targetListModeSchema.default("identifiers"),
+            output_mode: programListModeSchema.default("compact")
+        },
+        outputSchema: {
+            ...apiEnvelopeOutputShape,
+            source_requests: z.array(jsonRecordSchema).optional(),
+            resolved_program: jsonRecordSchema.optional(),
+            program_id: z.string().optional(),
+            targets: z.array(z.unknown()).optional(),
+            warnings: z.array(z.string()).optional(),
+            upstream_budget: jsonRecordSchema.optional(),
+            ranking_scope: jsonRecordSchema.optional(),
+            meta: jsonRecordSchema.optional()
+        },
+        annotations: readOnlyAnnotations
+    }, (args) => runTool("get_program_eligible_targets_by_name", config, rateLimiter, async () => getProgramEligibleTargetsByName(client, config, args)));
     server.registerTool("get_program_targets", {
         title: "Get Program Targets",
-        description: `Get active targets for one program. limit max ${MAX_TARGETS_PER_PROGRAM}.`,
+        description: `Get active targets for one known program_id. This is a final source for eligible target lists; do not call summary/breakdown unless grouped counts are needed. For a program name query, prefer get_program_eligible_targets_by_name. limit max ${MAX_TARGETS_PER_PROGRAM}.`,
         inputSchema: {
             program_id: programIdSchema,
             include_out_of_scope: z.boolean().default(false),
@@ -1488,7 +1528,20 @@ function registerResources(server, client, config, exportStore) {
         }));
     });
 }
+const programFallbackCache = new Map();
+const programTargetsFallbackCaches = new WeakMap();
+const resolveProgramCache = new Map();
 async function getProgramWithIdFallback(client, config, requestedProgramId) {
+    const cachedFallback = getCachedProgramFallback(config, requestedProgramId);
+    if (cachedFallback && !isProgramIndexFallback(cachedFallback)) {
+        return {
+            api: await client.getProgram(cachedFallback.resolvedProgramId),
+            programId: cachedFallback.resolvedProgramId,
+            sourceRequests: cachedFallback.sourceRequests,
+            warnings: cachedFallback.warnings,
+            fallback: cachedFallback
+        };
+    }
     try {
         return {
             api: await client.getProgram(requestedProgramId),
@@ -1505,6 +1558,7 @@ async function getProgramWithIdFallback(client, config, requestedProgramId) {
         if (!fallback) {
             throw error;
         }
+        rememberProgramFallback(config, fallback);
         return {
             api: await client.getProgram(fallback.resolvedProgramId),
             programId: fallback.resolvedProgramId,
@@ -1515,6 +1569,30 @@ async function getProgramWithIdFallback(client, config, requestedProgramId) {
     }
 }
 async function runProgramIdTool(client, config, requestedProgramId, callback, indexFallbackCallback) {
+    const cachedFallback = getCachedProgramFallback(config, requestedProgramId);
+    if (cachedFallback) {
+        if (isProgramIndexFallback(cachedFallback) && indexFallbackCallback) {
+            const payload = await indexFallbackCallback(cachedFallback);
+            return withProgramIndexFallbackMetadata(payload, cachedFallback);
+        }
+        try {
+            const payload = await callback(cachedFallback.resolvedProgramId);
+            return withProgramIdFallbackMetadata(payload, cachedFallback);
+        }
+        catch (cachedFallbackError) {
+            if (!isProgramNotFoundError(cachedFallbackError) || !indexFallbackCallback) {
+                throw cachedFallbackError;
+            }
+            const indexFallback = createProgramIndexFallbackFromStaleResolution(cachedFallback, requestedProgramId, cachedFallbackError) ??
+                (await resolveIndexedProgramId(client, config, cachedFallback.resolvedProgramId, cachedFallbackError));
+            if (!indexFallback) {
+                throw cachedFallbackError;
+            }
+            rememberProgramFallback(config, indexFallback);
+            const payload = await indexFallbackCallback(indexFallback);
+            return withProgramIndexFallbackMetadata(payload, indexFallback);
+        }
+    }
     try {
         return await callback(requestedProgramId);
     }
@@ -1531,10 +1609,12 @@ async function runProgramIdTool(client, config, requestedProgramId, callback, in
             if (!indexFallback) {
                 throw error;
             }
+            rememberProgramFallback(config, indexFallback);
             const payload = await indexFallbackCallback(indexFallback);
             return withProgramIndexFallbackMetadata(payload, indexFallback);
         }
         try {
+            rememberProgramFallback(config, fallback);
             const payload = await callback(fallback.resolvedProgramId);
             return withProgramIdFallbackMetadata(payload, fallback);
         }
@@ -1542,21 +1622,107 @@ async function runProgramIdTool(client, config, requestedProgramId, callback, in
             if (!isProgramNotFoundError(fallbackError) || !indexFallbackCallback) {
                 throw fallbackError;
             }
-            const indexFallback = await resolveIndexedProgramId(client, config, fallback.resolvedProgramId, fallbackError);
+            const indexFallback = createProgramIndexFallbackFromStaleResolution(fallback, requestedProgramId, fallbackError) ??
+                (await resolveIndexedProgramId(client, config, fallback.resolvedProgramId, fallbackError));
             if (!indexFallback) {
                 throw fallbackError;
             }
-            const combinedFallback = {
-                ...indexFallback,
-                requestedProgramId,
-                sourceRequests: [...fallback.sourceRequests, ...indexFallback.sourceRequests],
-                warnings: uniqueStrings([...fallback.warnings, ...indexFallback.warnings])
-            };
+            const combinedFallback = indexFallback.requestedProgramId === requestedProgramId
+                ? indexFallback
+                : {
+                    ...indexFallback,
+                    requestedProgramId,
+                    sourceRequests: [...fallback.sourceRequests, ...indexFallback.sourceRequests],
+                    warnings: uniqueStrings([...fallback.warnings, ...indexFallback.warnings])
+                };
+            rememberProgramFallback(config, combinedFallback);
             const payload = await indexFallbackCallback(combinedFallback);
             return withProgramIndexFallbackMetadata(payload, combinedFallback);
         }
     }
 }
+function getCachedProgramFallback(config, requestedProgramId) {
+    if (config.cacheTtlMs <= 0 || config.cacheMaxEntries <= 0) {
+        return undefined;
+    }
+    const key = programFallbackCacheKey(config, requestedProgramId);
+    const cached = programFallbackCache.get(key);
+    if (!cached) {
+        return undefined;
+    }
+    if (cached.expiresAt <= Date.now()) {
+        programFallbackCache.delete(key);
+        return undefined;
+    }
+    return cloneProgramFallbackForRequest(cached.fallback, requestedProgramId, true);
+}
+function rememberProgramFallback(config, fallback) {
+    if (config.cacheTtlMs <= 0 || config.cacheMaxEntries <= 0) {
+        return;
+    }
+    pruneProgramFallbackCache();
+    const key = programFallbackCacheKey(config, fallback.requestedProgramId);
+    programFallbackCache.set(key, {
+        expiresAt: Date.now() + config.cacheTtlMs,
+        fallback: cloneProgramFallbackForRequest(fallback, fallback.requestedProgramId, false)
+    });
+    if (programFallbackCache.size > PROGRAM_FALLBACK_CACHE_MAX_ENTRIES) {
+        const oldestKey = programFallbackCache.keys().next().value;
+        if (oldestKey) {
+            programFallbackCache.delete(oldestKey);
+        }
+    }
+}
+function pruneProgramFallbackCache() {
+    const now = Date.now();
+    for (const [key, cached] of programFallbackCache) {
+        if (cached.expiresAt <= now) {
+            programFallbackCache.delete(key);
+        }
+    }
+}
+function programFallbackCacheKey(config, requestedProgramId) {
+    return `${config.apiBaseUrl}\n${normalizeTag(requestedProgramId)}`;
+}
+function cloneProgramFallbackForRequest(fallback, requestedProgramId, fromCache) {
+    const warnings = fromCache
+        ? uniqueStrings([...fallback.warnings, `Reused cached program_id resolution for ${requestedProgramId}.`])
+        : [...fallback.warnings];
+    const cloned = {
+        ...fallback,
+        requestedProgramId,
+        warnings,
+        sourceRequests: [...fallback.sourceRequests],
+        resolution: { ...fallback.resolution }
+    };
+    if (isProgramIndexFallback(fallback)) {
+        const indexClone = {
+            ...cloned,
+            program: { ...fallback.program }
+        };
+        return indexClone;
+    }
+    return cloned;
+}
+function isProgramIndexFallback(fallback) {
+    return readObject(fallback.program) !== undefined;
+}
+function createProgramIndexFallbackFromStaleResolution(fallback, requestedProgramId, detailError) {
+    const match = selectProgramIndexFallbackMatch(fallback.resolvedProgramId, fallback.resolution);
+    if (!match) {
+        return undefined;
+    }
+    const detailApiError = detailError instanceof BBRadarApiError ? detailError : undefined;
+    const indexWarning = `program_id ${fallback.resolvedProgramId} exists in the BBRadar program index, but the per-program detail endpoint returned 404.`;
+    return {
+        ...fallback,
+        requestedProgramId,
+        staleRequestId: fallback.staleRequestId ?? detailApiError?.requestId,
+        staleUpstreamRequestId: fallback.staleUpstreamRequestId ?? detailApiError?.upstreamRequestId,
+        warnings: uniqueStrings([...fallback.warnings, indexWarning]),
+        program: match.program
+    };
+}
 async function resolveIndexedProgramId(client, config, requestedProgramId, staleError) {
     const query = programSearchText(requestedProgramId);
     if (query.length < 2) {
@@ -1747,6 +1913,10 @@ function withProgramIndexFallbackMetadata(payload, fallback) {
     };
 }
 async function resolveProgram(client, config, input) {
+    const cached = getCachedResolveProgram(config, input);
+    if (cached) {
+        return cached;
+    }
     const warnings = [];
     const budget = {
         initial: input.upstream_request_budget,
@@ -1756,6 +1926,8 @@ async function resolveProgram(client, config, input) {
     const searchQueries = programResolutionSearchQueries(input.query);
     const collected = await collectProgramsForResolution(client, {
         searchQueries,
+        isHighConfidenceMatch: (programs) => hasHighConfidenceProgramResolutionMatch(programs, config.webBaseUrl, input.query),
+        scorePrograms: (programs) => bestProgramResolutionScore(programs, config.webBaseUrl, input.query),
         platforms: input.platforms,
         tags: input.tags,
         opportunity_levels: input.opportunity_levels,
@@ -1773,7 +1945,7 @@ async function resolveProgram(client, config, input) {
         .sort((left, right) => right.match.score - left.match.score || compareProgramCandidates(left.candidate, right.candidate, "best_hunt_value"))
         .slice(0, input.max_results);
     const programs = matches.map((entry) => formatProgram(entry.candidate.program, input.output_mode));
-    return stripUndefined({
+    const payload = stripUndefined({
         request_id: randomUUID(),
         source_requests: collected.sourceRequests,
         warnings: warnings.length > 0 ? warnings : undefined,
@@ -1807,6 +1979,75 @@ async function resolveProgram(client, config, input) {
             upstream_requests_scanned: collected.requestsScanned
         }
     });
+    rememberResolveProgram(config, input, payload);
+    return payload;
+}
+function getCachedResolveProgram(config, input) {
+    if (config.cacheTtlMs <= 0 || config.cacheMaxEntries <= 0) {
+        return undefined;
+    }
+    const key = resolveProgramCacheKey(config, input);
+    const cached = resolveProgramCache.get(key);
+    if (!cached) {
+        return undefined;
+    }
+    if (cached.expiresAt <= Date.now()) {
+        resolveProgramCache.delete(key);
+        return undefined;
+    }
+    const sourceRequests = readArray(cached.payload.source_requests).filter((request) => readObject(request) !== undefined);
+    const warnings = readArray(cached.payload.warnings).filter((warning) => typeof warning === "string");
+    return stripUndefined({
+        ...cached.payload,
+        request_id: randomUUID(),
+        cache: {
+            hit: true,
+            expires_at: new Date(cached.expiresAt).toISOString()
+        },
+        source_requests: sourceRequests.map((request) => ({
+            ...request,
+            cache_hit: true,
+            cache_expires_at: new Date(cached.expiresAt).toISOString()
+        })),
+        warnings: uniqueStrings([...warnings, `Reused cached program resolution for ${input.query}.`])
+    });
+}
+function rememberResolveProgram(config, input, payload) {
+    if (config.cacheTtlMs <= 0 || config.cacheMaxEntries <= 0) {
+        return;
+    }
+    pruneResolveProgramCache();
+    resolveProgramCache.set(resolveProgramCacheKey(config, input), {
+        expiresAt: Date.now() + config.cacheTtlMs,
+        payload: { ...payload }
+    });
+    if (resolveProgramCache.size > PROGRAM_FALLBACK_CACHE_MAX_ENTRIES) {
+        const oldestKey = resolveProgramCache.keys().next().value;
+        if (oldestKey) {
+            resolveProgramCache.delete(oldestKey);
+        }
+    }
+}
+function pruneResolveProgramCache() {
+    const now = Date.now();
+    for (const [key, cached] of resolveProgramCache) {
+        if (cached.expiresAt <= now) {
+            resolveProgramCache.delete(key);
+        }
+    }
+}
+function resolveProgramCacheKey(config, input) {
+    return stableStringify({
+        apiBaseUrl: config.apiBaseUrl,
+        query: normalizeTag(input.query),
+        platforms: input.platforms.map(normalizeTag).sort(),
+        tags: input.tags.map(normalizeTag).sort(),
+        opportunity_levels: [...input.opportunity_levels].sort(),
+        max_pages: input.max_pages,
+        max_results: input.max_results,
+        output_mode: input.output_mode,
+        upstream_request_budget: input.upstream_request_budget
+    });
 }
 async function runProgramNameAction(client, config, input) {
     const resolution = await resolveProgram(client, config, {
@@ -1851,6 +2092,76 @@ async function runProgramNameAction(client, config, input) {
         ranking_scope: readObject(resolution.ranking_scope)
     });
 }
+async function getProgramEligibleTargetsByName(client, config, input) {
+    const resolution = await resolveProgram(client, config, {
+        query: input.query,
+        platforms: input.platforms,
+        tags: input.tags,
+        opportunity_levels: input.opportunity_levels,
+        max_pages: input.max_resolve_pages,
+        max_results: 1,
+        output_mode: input.output_mode,
+        upstream_request_budget: input.upstream_request_budget
+    });
+    const bestMatch = readObject(readArray(resolution.matches)[0]);
+    const programId = stringField(bestMatch, "program_id");
+    const resolvedProgram = readObject(bestMatch?.program);
+    const resolutionSourceRequests = readArray(resolution.source_requests).filter((request) => readObject(request) !== undefined);
+    const resolutionWarnings = readArray(resolution.warnings).filter((warning) => typeof warning === "string");
+    if (!programId) {
+        return stripUndefined({
+            request_id: randomUUID(),
+            source_requests: resolutionSourceRequests,
+            warnings: uniqueStrings([...resolutionWarnings, "No matching program_id was resolved for the requested program name."]),
+            resolved_program: undefined,
+            targets: [],
+            upstream_budget: readObject(resolution.upstream_budget),
+            ranking_scope: readObject(resolution.ranking_scope),
+            meta: {
+                found: false,
+                returned: 0,
+                query: input.query
+            }
+        });
+    }
+    const targetsPayload = await runProgramIdTool(client, config, programId, (resolvedProgramId) => getProgramTargetsPayload(client, {
+        include_out_of_scope: input.include_out_of_scope,
+        include_ineligible: input.include_ineligible,
+        strict_scope_filter: input.strict_scope_filter,
+        offset: input.offset,
+        limit: input.limit,
+        output_mode: input.target_list_mode
+    }, resolvedProgramId), (indexFallback) => getProgramTargetsExportFallbackPayload(client, {
+        include_out_of_scope: input.include_out_of_scope,
+        include_ineligible: input.include_ineligible,
+        strict_scope_filter: input.strict_scope_filter,
+        offset: input.offset,
+        limit: input.limit,
+        output_mode: input.target_list_mode
+    }, indexFallback.resolvedProgramId));
+    const targetSourceRequests = readArray(targetsPayload.source_requests).filter((request) => readObject(request) !== undefined);
+    const targetWarnings = readArray(targetsPayload.warnings).filter((warning) => typeof warning === "string");
+    const targetMeta = readObject(targetsPayload.meta);
+    return stripUndefined({
+        request_id: randomUUID(),
+        source_requests: [...resolutionSourceRequests, ...targetSourceRequests],
+        warnings: uniqueStrings([...resolutionWarnings, ...targetWarnings]),
+        resolved_program: resolvedProgram,
+        program_id: stringField(targetsPayload, "program_id") ?? programId,
+        targets: readArray(targetsPayload.targets),
+        upstream_budget: readObject(resolution.upstream_budget),
+        ranking_scope: readObject(resolution.ranking_scope),
+        program_id_resolution: readObject(targetsPayload.program_id_resolution),
+        meta: stripUndefined({
+            ...(targetMeta ?? {}),
+            found: true,
+            query: input.query,
+            target_filter: "in_scope_and_eligible_by_default",
+            resolve_request_id: stringField(resolution, "request_id"),
+            targets_request_id: stringField(targetsPayload, "request_id")
+        })
+    });
+}
 async function runResolvedProgramAction(client, config, programId, input) {
     if (input.action === "scope_delta") {
         return getProgramScopeDelta(client, config, {
@@ -2862,6 +3173,10 @@ async function getProgramTargetsExportFallbackPayload(client, input, programId)
     });
 }
 async function fetchProgramTargetsWithEndpointFallback(client, programId) {
+    const cachedLookup = getCachedProgramTargetsFallback(client, programId);
+    if (cachedLookup) {
+        return cachedLookup;
+    }
     try {
         const api = await client.getProgramTargets(programId);
         const data = readObject(api.data);
@@ -2894,9 +3209,86 @@ async function fetchProgramTargetsWithEndpointFallback(client, programId) {
         if (!isProgramNotFoundError(error)) {
             throw error;
         }
-        return fetchProgramTargetsFromExportFallback(client, programId);
+        const lookup = await fetchProgramTargetsFromExportFallback(client, programId);
+        rememberProgramTargetsFallback(client, programId, lookup);
+        return lookup;
+    }
+}
+function getCachedProgramTargetsFallback(client, programId) {
+    const diagnostics = client.diagnostics();
+    if (!diagnostics.response_cache.enabled) {
+        return undefined;
+    }
+    const cache = programTargetsFallbackCaches.get(client);
+    const key = programTargetsFallbackCacheKey(programId);
+    const cached = cache?.get(key);
+    if (!cached) {
+        return undefined;
+    }
+    if (cached.expiresAt <= Date.now()) {
+        cache?.delete(key);
+        return undefined;
+    }
+    return {
+        ...cached.lookup,
+        cache: readObject(stripUndefined({
+            ...(cached.lookup.cache ?? {}),
+            hit: true,
+            expires_at: new Date(cached.expiresAt).toISOString()
+        })),
+        sourceRequests: cached.lookup.sourceRequests.map((request) => ({
+            ...request,
+            cache_hit: true,
+            cache_expires_at: new Date(cached.expiresAt).toISOString()
+        })),
+        warnings: uniqueStrings([...cached.lookup.warnings, `Reused cached target fallback for ${programId}.`])
+    };
+}
+function rememberProgramTargetsFallback(client, programId, lookup) {
+    const diagnostics = client.diagnostics();
+    if (!diagnostics.response_cache.enabled || lookup.unavailable) {
+        return;
+    }
+    const cache = programTargetsFallbackCacheForClient(client);
+    pruneProgramTargetsFallbackCache(cache);
+    const ttlMs = cacheTtlMsFromDiagnostics(diagnostics.response_cache);
+    if (ttlMs <= 0) {
+        return;
+    }
+    cache.set(programTargetsFallbackCacheKey(programId), {
+        expiresAt: Date.now() + ttlMs,
+        lookup
+    });
+    if (cache.size > PROGRAM_FALLBACK_CACHE_MAX_ENTRIES) {
+        const oldestKey = cache.keys().next().value;
+        if (oldestKey) {
+            cache.delete(oldestKey);
+        }
+    }
+}
+function programTargetsFallbackCacheForClient(client) {
+    const existing = programTargetsFallbackCaches.get(client);
+    if (existing) {
+        return existing;
+    }
+    const cache = new Map();
+    programTargetsFallbackCaches.set(client, cache);
+    return cache;
+}
+function pruneProgramTargetsFallbackCache(cache) {
+    const now = Date.now();
+    for (const [key, cached] of cache) {
+        if (cached.expiresAt <= now) {
+            cache.delete(key);
+        }
     }
 }
+function programTargetsFallbackCacheKey(programId) {
+    return normalizeTag(programId);
+}
+function cacheTtlMsFromDiagnostics(cache) {
+    return cache.enabled ? cache.ttl_ms : 0;
+}
 async function fetchProgramTargetsFromExportFallback(client, programId) {
     try {
         const api = await client.exportTargets({
@@ -2952,6 +3344,93 @@ async function fetchProgramTargetsFromExportFallback(client, programId) {
         };
     }
 }
+async function getProgramFromTargetsOnlyFallback(client, programId, programError) {
+    const targetsApi = await client.getProgramTargets(programId);
+    const programApiError = programError instanceof BBRadarApiError ? programError : undefined;
+    return stripUndefined({
+        request_id: targetsApi.requestId,
+        fetched_at: targetsApi.fetchedAt,
+        cache: readObject(stripUndefined({
+            hit: targetsApi.cached,
+            coalesced_live_request: targetsApi.coalesced,
+            expires_at: targetsApi.cacheExpiresAt
+        })),
+        source_requests: [
+            stripUndefined({
+                source: "program",
+                program_id: programId,
+                failed: true,
+                request_id: programApiError?.requestId,
+                upstream_request_id: programApiError?.upstreamRequestId,
+                status: programApiError?.status
+            }),
+            {
+                source: "program_targets",
+                program_id: programId,
+                request_id: targetsApi.requestId,
+                upstream_request_id: targetsApi.upstreamRequestId,
+                ...apiSourceMetadata(targetsApi)
+            }
+        ],
+        warnings: [`Returned minimal program metadata because the per-program detail endpoint returned 404 for ${programId}, but the targets endpoint is available.`],
+        program: addProgramResourceLinks({ id: programId }),
+        meta: {
+            detail_source: "program_targets",
+            detail_endpoint_unavailable: true
+        }
+    });
+}
+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 targetsApi = targetsResult.value;
+    const targetSourceRequest = {
+        source: "program_targets",
+        request_id: targetsApi.requestId,
+        upstream_request_id: targetsApi.upstreamRequestId,
+        ...apiSourceMetadata(targetsApi)
+    };
+    if (programResult.status === "fulfilled") {
+        return {
+            program: addProgramResourceLinks(sanitizeProgram(programResult.value.data, config.webBaseUrl)),
+            targetsApi,
+            sourceRequests: [
+                {
+                    source: "program",
+                    request_id: programResult.value.requestId,
+                    upstream_request_id: programResult.value.upstreamRequestId,
+                    ...apiSourceMetadata(programResult.value)
+                },
+                targetSourceRequest
+            ],
+            warnings: [],
+            programDetailUnavailable: false
+        };
+    }
+    if (!isProgramNotFoundError(programResult.reason)) {
+        throw programResult.reason;
+    }
+    const programApiError = programResult.reason instanceof BBRadarApiError ? programResult.reason : undefined;
+    return {
+        program: addProgramResourceLinks({ id: programId }),
+        targetsApi,
+        sourceRequests: [
+            stripUndefined({
+                source: "program",
+                program_id: programId,
+                failed: true,
+                request_id: programApiError?.requestId,
+                upstream_request_id: programApiError?.upstreamRequestId,
+                status: programApiError?.status
+            }),
+            targetSourceRequest
+        ],
+        warnings: [`Used targets endpoint with minimal program metadata because the per-program detail endpoint returned 404 for ${programId}.`],
+        programDetailUnavailable: true
+    };
+}
 async function exportTargetsFromProgramTargetsFallback(client, config, exportStore, input, exportError) {
     const warnings = ["Target export endpoint is unavailable; assembled a fallback export from per-program target endpoints."];
     const sourceRequests = [
@@ -3075,8 +3554,8 @@ function readExportTargetRows(data) {
         .find((rows) => rows.length > 0) ?? [];
 }
 async function getProgramScopeSummary(client, config, input) {
-    const [programApi, targetsApi] = await Promise.all([client.getProgram(input.program_id), client.getProgramTargets(input.program_id)]);
-    const targetsData = readObject(targetsApi.data);
+    const lookup = await fetchProgramDetailsAndTargets(client, config, input.program_id);
+    const targetsData = readObject(lookup.targetsApi.data);
     const rawTargets = readArray(targetsData?.targets);
     const targets = rawTargets
         .map(sanitizeTarget)
@@ -3085,31 +3564,21 @@ async function getProgramScopeSummary(client, config, input) {
         include_ineligible: input.include_ineligible,
         strict_scope_filter: false
     }));
-    return {
+    return stripUndefined({
         request_id: randomUUID(),
-        source_requests: [
-            {
-                source: "program",
-                request_id: programApi.requestId,
-                upstream_request_id: programApi.upstreamRequestId,
-                ...apiSourceMetadata(programApi)
-            },
-            {
-                source: "program_targets",
-                request_id: targetsApi.requestId,
-                upstream_request_id: targetsApi.upstreamRequestId,
-                ...apiSourceMetadata(targetsApi)
-            }
-        ],
-        program: formatProgram(addProgramResourceLinks(sanitizeProgram(programApi.data, config.webBaseUrl)), "compact"),
+        source_requests: lookup.sourceRequests,
+        warnings: lookup.warnings.length > 0 ? lookup.warnings : undefined,
+        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,
             target_list_mode: input.target_list_mode,
-            group_limit: input.group_limit
+            group_limit: input.group_limit,
+            target_source: "program_targets",
+            detail_endpoint_unavailable: lookup.programDetailUnavailable || undefined
         }
-    };
+    });
 }
 async function getProgramScopeSummaryFromIndexFallback(client, indexFallback, input) {
     const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, input.program_id);
@@ -3139,8 +3608,8 @@ async function getProgramScopeSummaryFromIndexFallback(client, indexFallback, in
     });
 }
 async function getProgramTargetBreakdown(client, config, input) {
-    const [programApi, targetsApi] = await Promise.all([client.getProgram(input.program_id), client.getProgramTargets(input.program_id)]);
-    const targetsData = readObject(targetsApi.data);
+    const lookup = await fetchProgramDetailsAndTargets(client, config, input.program_id);
+    const targetsData = readObject(lookup.targetsApi.data);
     const rawTargets = readArray(targetsData?.targets);
     const targets = rawTargets
         .map(sanitizeTarget)
@@ -3150,23 +3619,11 @@ async function getProgramTargetBreakdown(client, config, input) {
         strict_scope_filter: false
     }));
     const scope = buildTargetScopeSummary(targets, input.target_list_mode, input.group_limit, input.include_out_of_scope, input.include_ineligible);
-    return {
+    return stripUndefined({
         request_id: randomUUID(),
-        source_requests: [
-            {
-                source: "program",
-                request_id: programApi.requestId,
-                upstream_request_id: programApi.upstreamRequestId,
-                ...apiSourceMetadata(programApi)
-            },
-            {
-                source: "program_targets",
-                request_id: targetsApi.requestId,
-                upstream_request_id: targetsApi.upstreamRequestId,
-                ...apiSourceMetadata(targetsApi)
-            }
-        ],
-        program: formatProgram(addProgramResourceLinks(sanitizeProgram(programApi.data, config.webBaseUrl)), "compact"),
+        source_requests: lookup.sourceRequests,
+        warnings: lookup.warnings.length > 0 ? lookup.warnings : undefined,
+        program: formatProgram(lookup.program, "compact"),
         breakdown: {
             target_counts: readObject(scope.target_counts),
             by_target_type: countTargetValues(targets, (target) => stringField(target, "target_type")),
@@ -3180,9 +3637,11 @@ async function getProgramTargetBreakdown(client, config, input) {
             total_active_targets: rawTargets.length,
             total_after_filters: targets.length,
             target_list_mode: input.target_list_mode,
-            group_limit: input.group_limit
+            group_limit: input.group_limit,
+            target_source: "program_targets",
+            detail_endpoint_unavailable: lookup.programDetailUnavailable || undefined
         }
-    };
+    });
 }
 async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback, input) {
     const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, input.program_id);
@@ -3632,14 +4091,13 @@ async function checkWatchlistNewTargets(client, config, input) {
     });
 }
 async function getProgramBrief(client, config, input) {
-    const programPromise = client.getProgram(input.program_id);
-    const targetsPromise = client.getProgramTargets(input.program_id);
+    const detailsAndTargetsPromise = fetchProgramDetailsAndTargets(client, config, input.program_id);
     const changesPromise = input.include_recent_changes && input.recent_changes_limit > 0
         ? fetchProgramChanges(client, config, input.program_id, input.recent_changes_limit, true, input.include_ineligible, input.include_out_of_scope)
         : Promise.resolve(undefined);
-    const [programApi, targetsApi, changes] = await Promise.all([programPromise, targetsPromise, changesPromise]);
-    const candidate = toProgramCandidate(programApi.data, config.webBaseUrl);
-    const targetsData = readObject(targetsApi.data);
+    const [lookup, changes] = await Promise.all([detailsAndTargetsPromise, changesPromise]);
+    const candidate = toProgramCandidate(lookup.program, config.webBaseUrl);
+    const targetsData = readObject(lookup.targetsApi.data);
     const rawTargets = readArray(targetsData?.targets);
     const targets = rawTargets
         .map(sanitizeTarget)
@@ -3651,21 +4109,8 @@ async function getProgramBrief(client, config, input) {
     const scope = buildTargetScopeSummary(targets, input.target_list_mode, input.target_sample_size, input.include_out_of_scope, input.include_ineligible);
     return stripUndefined({
         request_id: randomUUID(),
-        source_requests: [
-            {
-                source: "program",
-                request_id: programApi.requestId,
-                upstream_request_id: programApi.upstreamRequestId,
-                ...apiSourceMetadata(programApi)
-            },
-            {
-                source: "program_targets",
-                request_id: targetsApi.requestId,
-                upstream_request_id: targetsApi.upstreamRequestId,
-                ...apiSourceMetadata(targetsApi)
-            },
-            ...(changes?.sourceRequests ?? [])
-        ],
+        source_requests: [...lookup.sourceRequests, ...(changes?.sourceRequests ?? [])],
+        warnings: lookup.warnings.length > 0 ? lookup.warnings : undefined,
         program: formatProgram(candidate.program, "compact"),
         brief: {
             rank_factors: rankFactors(candidate),
@@ -3681,7 +4126,9 @@ async function getProgramBrief(client, config, input) {
             total_active_targets: rawTargets.length,
             total_targets_after_filters: targets.length,
             recent_changes_returned: changes?.changes.length ?? 0,
-            target_list_mode: input.target_list_mode
+            target_list_mode: input.target_list_mode,
+            target_source: "program_targets",
+            detail_endpoint_unavailable: lookup.programDetailUnavailable || undefined
         }
     });
 }
@@ -4278,6 +4725,12 @@ function programResolutionMatch(candidate, query) {
         reasons: [...reasons]
     };
 }
+function hasHighConfidenceProgramResolutionMatch(programs, webBaseUrl, query) {
+    return programs.some((program) => programResolutionMatch(toProgramCandidate(program, webBaseUrl), query).score >= 85);
+}
+function bestProgramResolutionScore(programs, webBaseUrl, query) {
+    return programs.reduce((best, program) => Math.max(best, programResolutionMatch(toProgramCandidate(program, webBaseUrl), query).score), 0);
+}
 function programResolutionSearchQueries(query) {
     return programResolutionQueryVariants(query).slice(0, MAX_RESOLVE_SEARCH_QUERIES);
 }
@@ -4285,11 +4738,20 @@ function programResolutionQueryVariants(query) {
     const normalized = normalizeTag(query);
     const meaningfulTokens = [...meaningfulProgramQueryTokens(query)];
     const meaningfulPhrase = meaningfulTokens.join(" ");
+    const singleTokenNameVariants = meaningfulTokens.length === 1
+        ? [
+            `${meaningfulTokens[0]} network`,
+            `${meaningfulTokens[0]} protocol`,
+            `${meaningfulTokens[0]} bug bounty`,
+            `${meaningfulTokens[0]} bounty`
+        ]
+        : [];
     const values = [
         normalized,
         meaningfulPhrase,
         meaningfulTokens.join("-"),
-        ...meaningfulTokens
+        ...meaningfulTokens,
+        ...singleTokenNameVariants
     ];
     return uniqueStrings(values.filter((value) => value.length >= 2));
 }
@@ -4504,22 +4966,48 @@ async function collectPrograms(client, options) {
 }
 async function collectProgramsForResolution(client, options) {
     const collections = [];
+    const queryCollections = [];
     const queries = options.searchQueries.length > 0 ? options.searchQueries : [undefined];
     for (const search of queries) {
         if (options.budget.remaining <= 0) {
             addUniqueWarning(options.warnings, "Upstream request budget was exhausted before all program name search variants could be checked.");
             break;
         }
-        collections.push(await collectPrograms(client, {
+        const collection = await collectPrograms(client, {
             search,
             platforms: options.platforms,
             tags: options.tags,
             updated_since: undefined,
             opportunity_levels: options.opportunity_levels,
-            max_pages: options.max_pages,
+            max_pages: 1,
             budget: options.budget,
             warnings: options.warnings
-        }));
+        });
+        collections.push(collection);
+        queryCollections.push({ search, collection });
+        if (options.isHighConfidenceMatch?.(mergeProgramCollections(collections).programs)) {
+            return mergeProgramCollections(collections);
+        }
+    }
+    if (options.max_pages > 1) {
+        const search = bestResolutionDeepSearch(queryCollections, options.scorePrograms) ?? queries[0];
+        if (options.budget.remaining <= 0) {
+            addUniqueWarning(options.warnings, "Upstream request budget was exhausted before more program name result pages could be checked.");
+        }
+        else if (search !== undefined || queries.length > 0) {
+            const collection = await collectPrograms(client, {
+                search,
+                platforms: options.platforms,
+                tags: options.tags,
+                updated_since: undefined,
+                opportunity_levels: options.opportunity_levels,
+                max_pages: options.max_pages,
+                start_page: 2,
+                budget: options.budget,
+                warnings: options.warnings
+            });
+            collections.push(collection);
+        }
     }
     if (collections.length === 0) {
         return {
@@ -4532,6 +5020,16 @@ async function collectProgramsForResolution(client, options) {
     }
     return mergeProgramCollections(collections);
 }
+function bestResolutionDeepSearch(queryCollections, scorePrograms) {
+    if (queryCollections.length === 0) {
+        return undefined;
+    }
+    if (!scorePrograms) {
+        return queryCollections[0]?.search;
+    }
+    return [...queryCollections]
+        .sort((left, right) => scorePrograms(right.collection.programs) - scorePrograms(left.collection.programs))[0]?.search;
+}
 function mergeProgramCollections(collections) {
     const programs = new Map();
     const totalPagesBySource = {};
@@ -4559,6 +5057,18 @@ async function collectProgramSources(client, sources, options) {
     return pages;
 }
 async function collectProgramSource(client, source, sourceIndex, options) {
+    const startPage = Math.max(1, options.start_page ?? 1);
+    if (startPage > 1) {
+        const pageNumbers = Array.from({ length: Math.max(0, options.max_pages - startPage + 1) }, (_, index) => startPage + index);
+        const pages = [];
+        await mapWithConcurrency(pageNumbers, PROGRAM_COLLECTION_CONCURRENCY, async (page) => {
+            const result = await fetchProgramPage(client, source, sourceIndex, page, options);
+            if (result) {
+                pages.push(result);
+            }
+        });
+        return pages;
+    }
     const firstPage = await fetchProgramPage(client, source, sourceIndex, 1, options);
     if (!firstPage) {
         return [];
@@ -5023,7 +5533,8 @@ Find the best BBRadar program candidates.
 - Apply tag filters from this JSON string if provided: ${promptJson(args.tags ?? "")}.
 - Keep the shortlist to this JSON value: ${promptJson(args.max_programs ?? "10")}.
 - Compare freshness, opportunity score, reward range, public report count, target counts, and scope tags.
-- For exact scope details on one candidate, call get_program_scope_summary or get_program_target_breakdown before falling back to get_program_targets.
+- For a user asking for an in-scope or bounty-eligible target list by program name, call get_program_eligible_targets_by_name once and treat its target list as final.
+- For an already known program_id, call get_program_targets directly for exact target lists. Use get_program_scope_summary or get_program_target_breakdown only when grouped counts are needed.
 - Return a ranked list with concise rationale, likely target themes, and BBRadar URLs.
 - Stay passive-only; do not recommend scanning, probing, exploit attempts, or direct contact with targets.`));
     server.registerPrompt("summarize_program_scope", {
@@ -5032,7 +5543,7 @@ Find the best BBRadar program candidates.
         argsSchema: {
             program_id: programIdSchema
         }
-    }, (args) => promptResult(`Use get_program for the program_id in this JSON string: ${promptJson(args.program_id)}. Then use get_program_targets with include_out_of_scope=false, include_ineligible=false, and limit=${MAX_TARGETS_PER_PROGRAM}. Only request out-of-scope or ineligible targets if the user explicitly asks for them.
+    }, (args) => promptResult(`Use get_program_targets for the program_id in this JSON string: ${promptJson(args.program_id)} with include_out_of_scope=false, include_ineligible=false, and limit=${MAX_TARGETS_PER_PROGRAM}. Do not call get_program first unless program metadata is explicitly needed. Only request out-of-scope or ineligible targets if the user explicitly asks for them.
 
 Summarize the program scope:
 - Program name, platform, reward range, public report count, first seen date, last updated date, and BBRadar URL.
@@ -5053,7 +5564,8 @@ Summarize the program scope:
 Do not invoke local bug bounty skills, methodology files, worklogs, or non-BBRadar tools unless the user explicitly asks for external methodology.
 
 Use BBRadar MCP data first:
-- If a program_id is provided, call get_program and get_program_targets.
+- If a program_id is provided, call get_program_targets first. Call get_program only if metadata is explicitly needed.
+- If the user provides a program name and asks for in-scope or bounty-eligible targets, call get_program_eligible_targets_by_name once.
 - If no program_id is provided, call get_opportunities and select a small set of candidate programs before planning.
 - Focus area JSON string: ${promptJson(args.focus ?? "highest-signal in-scope bounty-eligible targets")}.