@bbradar/mcp 0.1.6 → 0.1.8

package/dist/server.js

@@ -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"];
@@ -92,10 +93,9 @@ const filterValueSchema = z
     message: "Filter values cannot contain commas or control characters."
 });
 const stringListSchema = z
-    .array(filterValueSchema)
-    .max(50)
-    .default([])
+    .preprocess(normalizeStringListInput, z.array(filterValueSchema).max(50).default([]))
     .describe("Filter values.");
+const acceptedTargetLimitSchema = z.number().int().min(1).max(MAX_TARGETS_PER_PROGRAM);
 const searchTextSchema = z
     .string()
     .trim()
@@ -329,7 +329,7 @@ export function createBbradarServer(client, config) {
             include_out_of_scope: z.boolean().default(false),
             include_ineligible: z.boolean().default(false),
             page_size: recentChangesPageSizeSchema.default(MAX_RECENT_CHANGES),
-            max_targets: z.number().int().min(1).max(MAX_RECENT_CHANGES).default(25),
+            max_targets: acceptedTargetLimitSchema.default(25),
             group_limit: z.number().int().min(1).max(MAX_TARGETS_PER_PROGRAM).default(100),
             target_list_mode: targetListModeSchema.default("identifiers"),
             max_resolve_pages: z.number().int().min(1).max(MAX_ACCEPTED_NUMERIC_LIMIT).default(3),
@@ -486,7 +486,7 @@ export function createBbradarServer(client, config) {
             include_out_of_scope: z.boolean().default(false),
             include_ineligible: z.boolean().default(false),
             page_size: recentChangesPageSizeSchema.default(MAX_RECENT_CHANGES),
-            max_targets: z.number().int().min(1).max(MAX_RECENT_CHANGES).default(50),
+            max_targets: acceptedTargetLimitSchema.default(50),
             target_list_mode: targetListModeSchema.default("identifiers")
         },
         outputSchema: {
@@ -498,7 +498,7 @@ export function createBbradarServer(client, config) {
             meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
-    }, (args) => runTool("get_program_scope_delta", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramScopeDelta(client, config, { ...args, program_id: programId }))));
+    }, (args) => runTool("get_program_scope_delta", config, rateLimiter, async () => runProgramIdTool(client, config, args.program_id, (programId) => getProgramScopeDelta(client, config, { ...args, program_id: programId }), (indexFallback) => getProgramScopeDeltaFromIndexedProgram(client, config, { ...args, program_id: indexFallback.resolvedProgramId }, indexFallback.program))));
     server.registerTool("get_recent_target_activity", {
         title: "Get Recent Target Activity",
         description: "Recent target changes grouped by program.",
@@ -534,7 +534,7 @@ export function createBbradarServer(client, config) {
             target_type: filterValueSchema.optional(),
             include_ineligible: z.boolean().default(false).describe("Include ineligible."),
             page_size: recentChangesPageSizeSchema.default(MAX_RECENT_CHANGES),
-            max_targets: z.number().int().min(1).max(MAX_RECENT_CHANGES).default(25),
+            max_targets: acceptedTargetLimitSchema.default(25),
             target_list_mode: targetListModeSchema.default("identifiers")
         },
         outputSchema: {
@@ -1366,24 +1366,33 @@ export function createBbradarServer(client, config) {
         },
         outputSchema: {
             ...apiEnvelopeOutputShape,
-            export: z.unknown().optional()
+            export: z.unknown().optional(),
+            meta: jsonRecordSchema.optional()
         },
         annotations: readOnlyAnnotations
     }, (args) => runTool("export_targets", config, rateLimiter, async () => {
-        const api = await client.exportTargets(compactRecord(args));
-        const exportId = randomUUID();
-        const sanitizedExport = sanitizeTargetsForExport(api.data, args.limit);
-        const resourceUri = exportResourceUri(exportId);
-        rememberExport(exportStore, exportId, sanitizedExport);
-        return withApiMetadata(api, {
-            export: {
-                export_id: exportId,
-                resource_uri: resourceUri,
-                preview: previewExportPayload(sanitizedExport),
-                returned_preview_count: previewExportCount(sanitizedExport),
-                limit: args.limit
+        try {
+            const api = await client.exportTargets(compactRecord(args));
+            const exportId = randomUUID();
+            const sanitizedExport = sanitizeTargetsForExport(api.data, args.limit);
+            const resourceUri = exportResourceUri(exportId);
+            rememberExport(exportStore, exportId, sanitizedExport);
+            return withApiMetadata(api, {
+                export: {
+                    export_id: exportId,
+                    resource_uri: resourceUri,
+                    preview: previewExportPayload(sanitizedExport),
+                    returned_preview_count: previewExportCount(sanitizedExport),
+                    limit: args.limit
+                }
+            });
+        }
+        catch (error) {
+            if (!(error instanceof BBRadarApiError) || (error.status !== 404 && error.status !== 405)) {
+                throw error;
             }
-        });
+            return exportTargetsFromProgramTargetsFallback(client, config, exportStore, args, error);
+        }
     }));
     registerPrompts(server);
     registerResources(server, client, config, exportStore);
@@ -1480,7 +1489,19 @@ function registerResources(server, client, config, exportStore) {
         }));
     });
 }
+const programFallbackCache = new Map();
+const programTargetsFallbackCaches = new WeakMap();
 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),
@@ -1497,6 +1518,7 @@ async function getProgramWithIdFallback(client, config, requestedProgramId) {
         if (!fallback) {
             throw error;
         }
+        rememberProgramFallback(config, fallback);
         return {
             api: await client.getProgram(fallback.resolvedProgramId),
             programId: fallback.resolvedProgramId,
@@ -1507,6 +1529,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);
     }
@@ -1523,10 +1569,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);
         }
@@ -1534,21 +1582,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) {
@@ -2827,7 +2961,7 @@ async function getProgramTargetsPayload(client, input, programId) {
     });
 }
 async function getProgramTargetsExportFallbackPayload(client, input, programId) {
-    const exportLookup = await fetchProgramTargetsFromExportFallback(client, programId);
+    const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, programId);
     const sanitizedTargets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, input));
     const targets = sanitizedTargets.slice(input.offset, input.offset + input.limit);
     return stripUndefined({
@@ -2853,6 +2987,123 @@ 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);
+        const rawTargets = readArray(data?.targets).map(sanitizeTarget);
+        return {
+            requestId: api.requestId,
+            upstreamRequestId: api.upstreamRequestId,
+            fetchedAt: api.fetchedAt,
+            cache: readObject(stripUndefined({
+                hit: api.cached,
+                coalesced_live_request: api.coalesced,
+                expires_at: api.cacheExpiresAt
+            })),
+            source: "program_targets",
+            rawTargets,
+            sourceRequests: [
+                {
+                    source: "program_targets",
+                    program_id: programId,
+                    request_id: api.requestId,
+                    upstream_request_id: api.upstreamRequestId,
+                    ...apiSourceMetadata(api)
+                }
+            ],
+            warnings: [],
+            unavailable: false
+        };
+    }
+    catch (error) {
+        if (!isProgramNotFoundError(error)) {
+            throw error;
+        }
+        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({
@@ -2908,6 +3159,116 @@ async function fetchProgramTargetsFromExportFallback(client, programId) {
         };
     }
 }
+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 = [
+        {
+            source: "target_export",
+            failed: true,
+            request_id: exportError.requestId,
+            upstream_request_id: exportError.upstreamRequestId,
+            status: exportError.status
+        }
+    ];
+    const programIds = input.program_ids.length > 0 ? input.program_ids : await discoverExportProgramIds(client, input, sourceRequests, warnings);
+    const targets = [];
+    const errors = [];
+    for (const programId of programIds) {
+        if (targets.length >= input.limit) {
+            break;
+        }
+        try {
+            const payload = 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: false,
+                offset: 0,
+                limit: input.limit - targets.length,
+                output_mode: "full"
+            }, resolvedProgramId), (indexFallback) => getProgramTargetsExportFallbackPayload(client, {
+                include_out_of_scope: input.include_out_of_scope,
+                include_ineligible: input.include_ineligible,
+                strict_scope_filter: false,
+                offset: 0,
+                limit: input.limit - targets.length,
+                output_mode: "full"
+            }, indexFallback.resolvedProgramId));
+            const resolvedProgramId = stringField(payload, "program_id") ?? programId;
+            sourceRequests.push(...readArray(payload.source_requests).filter((request) => readObject(request) !== undefined));
+            warnings.push(...readArray(payload.warnings).filter((warning) => typeof warning === "string"));
+            for (const target of readArray(payload.targets)) {
+                const object = readObject(target);
+                if (!object) {
+                    continue;
+                }
+                targets.push({ program_id: resolvedProgramId, ...object });
+                if (targets.length >= input.limit) {
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            errors.push(apiOperationError(programId, error));
+        }
+    }
+    if (input.format === "csv") {
+        warnings.push("Fallback target export returns JSON even when CSV was requested.");
+    }
+    const exportPayload = stripUndefined({
+        targets,
+        meta: {
+            export_source: "program_targets_fallback",
+            requested_program_count: programIds.length,
+            returned: targets.length,
+            limit: input.limit,
+            format: "json"
+        },
+        generated_at: new Date().toISOString()
+    });
+    const exportId = randomUUID();
+    const resourceUri = exportResourceUri(exportId);
+    rememberExport(exportStore, exportId, exportPayload);
+    return stripUndefined({
+        request_id: randomUUID(),
+        source_requests: sourceRequests,
+        warnings: uniqueStrings(warnings),
+        errors: errors.length > 0 ? errors : undefined,
+        export: {
+            export_id: exportId,
+            resource_uri: resourceUri,
+            preview: previewExportPayload(exportPayload),
+            returned_preview_count: previewExportCount(exportPayload),
+            limit: input.limit
+        },
+        meta: stripUndefined({
+            export_source: "program_targets_fallback",
+            requested_program_count: programIds.length,
+            returned: targets.length,
+            failed_program_count: errors.length,
+            fallback_error: apiOperationError("target_export", exportError)
+        })
+    });
+}
+async function discoverExportProgramIds(client, input, sourceRequests, warnings) {
+    const budget = {
+        initial: 1,
+        remaining: 1
+    };
+    const collected = await collectPrograms(client, {
+        platforms: input.platforms,
+        tags: input.tags,
+        updated_since: undefined,
+        opportunity_levels: input.opportunity_levels,
+        max_pages: 1,
+        budget,
+        warnings
+    });
+    sourceRequests.push(...collected.sourceRequests);
+    return uniqueStrings(collected.programs
+        .map((program) => stringField(sanitizeProgram(program, ""), "id"))
+        .filter((programId) => programId !== undefined)
+        .slice(0, input.limit));
+}
 function readExportTargetRows(data) {
     if (Array.isArray(data)) {
         return data;
@@ -2958,7 +3319,7 @@ async function getProgramScopeSummary(client, config, input) {
     };
 }
 async function getProgramScopeSummaryFromIndexFallback(client, indexFallback, input) {
-    const exportLookup = await fetchProgramTargetsFromExportFallback(client, input.program_id);
+    const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, input.program_id);
     const targets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, {
         include_out_of_scope: input.include_out_of_scope,
         include_ineligible: input.include_ineligible,
@@ -3031,7 +3392,7 @@ async function getProgramTargetBreakdown(client, config, input) {
     };
 }
 async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback, input) {
-    const exportLookup = await fetchProgramTargetsFromExportFallback(client, input.program_id);
+    const exportLookup = await fetchProgramTargetsWithEndpointFallback(client, input.program_id);
     const targets = exportLookup.rawTargets.filter((target) => targetHasAllowedScope(target, {
         include_out_of_scope: input.include_out_of_scope,
         include_ineligible: input.include_ineligible,
@@ -3069,19 +3430,8 @@ async function getProgramTargetBreakdownFromIndexFallback(client, indexFallback,
 async function getProgramScopeDelta(client, config, input) {
     const programApi = await client.getProgram(input.program_id);
     const program = addProgramResourceLinks(sanitizeProgram(programApi.data, config.webBaseUrl));
-    const changesPayload = await fetchProgramChanges(client, config, input.program_id, input.page_size, input.include_removed || input.change_type === "removed", input.include_ineligible, input.include_out_of_scope);
-    const sinceTimestamp = input.since ? Date.parse(input.since) : undefined;
-    const filteredChanges = changesPayload.changes
-        .filter((change) => !input.change_type || stringField(change, "change_type") === input.change_type)
-        .filter((change) => sinceTimestamp === undefined || timestampField(change, "changed_at") >= sinceTimestamp)
-        .filter((change) => {
-        const target = readObject(change.target);
-        return !input.target_type || (target !== undefined && targetMatchesRequestedType(target, input.target_type));
-    })
-        .filter((change) => {
-        const target = readObject(change.target);
-        return input.language_tags.length === 0 || (target !== undefined && targetMatchesAnySignal(target, input.language_tags));
-    });
+    const changesPayload = await fetchProgramChanges(client, config, input.program_id, input.page_size, input.include_removed || input.change_type === "removed", input.include_ineligible, input.include_out_of_scope, input.max_targets);
+    const filteredChanges = filterProgramScopeDeltaChanges(changesPayload.changes, input);
     const limitedChanges = filteredChanges.slice(0, input.max_targets);
     return stripUndefined({
         request_id: randomUUID(),
@@ -3106,10 +3456,55 @@ async function getProgramScopeDelta(client, config, input) {
             change_type: input.change_type,
             target_type: input.target_type,
             language_tags: input.language_tags.length > 0 ? input.language_tags : undefined,
-            target_list_mode: input.target_list_mode
+            target_list_mode: input.target_list_mode,
+            upstream_total_pages: readNumber(changesPayload.meta?.total_pages),
+            pages_fetched: readNumber(changesPayload.meta?.pages_fetched),
+            scan_may_be_incomplete: (readNumber(changesPayload.meta?.total_pages) ?? 1) > (readNumber(changesPayload.meta?.pages_fetched) ?? 1)
         })
     });
 }
+async function getProgramScopeDeltaFromIndexedProgram(client, config, input, indexedProgram) {
+    const program = addProgramResourceLinks(indexedProgram);
+    const changesPayload = await fetchProgramChanges(client, config, input.program_id, input.page_size, input.include_removed || input.change_type === "removed", input.include_ineligible, input.include_out_of_scope, input.max_targets);
+    const filteredChanges = filterProgramScopeDeltaChanges(changesPayload.changes, input);
+    const limitedChanges = filteredChanges.slice(0, input.max_targets);
+    return stripUndefined({
+        request_id: randomUUID(),
+        source_requests: changesPayload.sourceRequests,
+        program: formatProgram(program, "compact"),
+        delta: buildScopeDelta(limitedChanges, input.target_list_mode),
+        changes: limitedChanges.map((change) => formatChange(change, "compact")),
+        meta: stripUndefined({
+            recent_changes_scanned: changesPayload.changes.length,
+            changes_after_filters: filteredChanges.length,
+            returned: limitedChanges.length,
+            has_more: filteredChanges.length > limitedChanges.length,
+            since: input.since,
+            change_type: input.change_type,
+            target_type: input.target_type,
+            language_tags: input.language_tags.length > 0 ? input.language_tags : undefined,
+            target_list_mode: input.target_list_mode,
+            program_detail_source: "program_index",
+            upstream_total_pages: readNumber(changesPayload.meta?.total_pages),
+            pages_fetched: readNumber(changesPayload.meta?.pages_fetched),
+            scan_may_be_incomplete: (readNumber(changesPayload.meta?.total_pages) ?? 1) > (readNumber(changesPayload.meta?.pages_fetched) ?? 1)
+        })
+    });
+}
+function filterProgramScopeDeltaChanges(changes, input) {
+    const sinceTimestamp = input.since ? Date.parse(input.since) : undefined;
+    return changes
+        .filter((change) => !input.change_type || stringField(change, "change_type") === input.change_type)
+        .filter((change) => sinceTimestamp === undefined || timestampField(change, "changed_at") >= sinceTimestamp)
+        .filter((change) => {
+        const target = readObject(change.target);
+        return !input.target_type || (target !== undefined && targetMatchesRequestedType(target, input.target_type));
+    })
+        .filter((change) => {
+        const target = readObject(change.target);
+        return input.language_tags.length === 0 || (target !== undefined && targetMatchesAnySignal(target, input.language_tags));
+    });
+}
 async function getRecentTargetActivity(client, config, input) {
     const query = toQuery({
         change_type: input.change_type,
@@ -3517,32 +3912,45 @@ async function getProgramDelta(client, config, input) {
         meta: changes.meta
     };
 }
-async function fetchProgramChanges(client, config, programId, pageSize, includeRemoved, includeIneligible, includeOutOfScope) {
+async function fetchProgramChanges(client, config, programId, pageSize, includeRemoved, includeIneligible, includeOutOfScope, maxChanges = pageSize) {
     const handle = programSearchText(programId);
-    const api = await client.getRecentChanges({
-        search: handle.length >= 2 ? handle : programId,
-        include_removed: includeRemoved,
-        include_ineligible: includeIneligible,
-        include_out_of_scope: includeOutOfScope,
-        page: 1,
-        page_size: pageSize
-    });
-    const data = readObject(api.data);
-    const changes = readArray(data?.results)
-        .map((change) => sanitizeChange(change, config.webBaseUrl))
-        .filter((change) => stringField(readObject(change.program), "id") === programId);
-    return {
-        changes,
-        meta: sanitizeJson(data?.meta),
-        sourceRequests: [
-            {
-                source: "recent_changes",
-                request_id: api.requestId,
-                upstream_request_id: api.upstreamRequestId,
-                ...apiSourceMetadata(api)
-            }
-        ]
-    };
+    const changes = [];
+    const sourceRequests = [];
+    let meta;
+    const maxPages = Math.max(1, Math.ceil(maxChanges / pageSize));
+    for (let page = 1; page <= maxPages && changes.length < maxChanges; page += 1) {
+        const api = await client.getRecentChanges({
+            search: handle.length >= 2 ? handle : programId,
+            include_removed: includeRemoved,
+            include_ineligible: includeIneligible,
+            include_out_of_scope: includeOutOfScope,
+            page,
+            page_size: pageSize
+        });
+        const data = readObject(api.data);
+        const pageMeta = readObject(sanitizeJson(data?.meta));
+        const rows = readArray(data?.results);
+        meta = {
+            ...(meta ?? {}),
+            ...(pageMeta ?? {}),
+            pages_fetched: page
+        };
+        sourceRequests.push({
+            source: "recent_changes",
+            request_id: api.requestId,
+            upstream_request_id: api.upstreamRequestId,
+            page,
+            ...apiSourceMetadata(api)
+        });
+        changes.push(...rows
+            .map((change) => sanitizeChange(change, config.webBaseUrl))
+            .filter((change) => stringField(readObject(change.program), "id") === programId));
+        const totalPages = readNumber(pageMeta?.total_pages);
+        if (rows.length === 0 || (totalPages !== undefined && page >= totalPages)) {
+            break;
+        }
+    }
+    return { changes: changes.slice(0, maxChanges), meta, sourceRequests };
 }
 function addProgramResourceLinks(program) {
     const id = stringField(program, "id");
@@ -4136,6 +4544,23 @@ function programFetchError(programId, error) {
         suggested_fix: "Retry the program lookup or verify the BBRadar program id."
     };
 }
+function apiOperationError(operation, error) {
+    if (error instanceof BBRadarApiError) {
+        return stripUndefined({
+            operation,
+            request_id: error.requestId,
+            upstream_request_id: error.upstreamRequestId,
+            status: error.status,
+            message: error.message,
+            detail: sanitizeJson(error.detail),
+            errors: sanitizeJson(error.errors)
+        });
+    }
+    return {
+        operation,
+        message: error instanceof Error ? error.message : String(error)
+    };
+}
 function programSearchText(programId) {
     const colonIndex = programId.indexOf(":");
     const handle = colonIndex >= 0 ? programId.slice(colonIndex + 1) : programId;
@@ -4999,6 +5424,21 @@ function toRateLimitPayload(decision) {
 function rateLimitForTool(toolName, config) {
     return toolName === "export_targets" ? config.exportRateLimitPerMinute : config.defaultRateLimitPerMinute;
 }
+function normalizeStringListInput(value) {
+    if (typeof value === "string") {
+        return splitFilterList(value);
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((entry) => (typeof entry === "string" ? splitFilterList(entry) : [entry]));
+    }
+    return value;
+}
+function splitFilterList(value) {
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
 function toQuery(values) {
     return compactRecord(values);
 }