@bbradar/mcp 0.1.19 → 0.2.0

package/dist/bbradarClient.js

@@ -2,12 +2,26 @@ import { randomUUID } from "node:crypto";
 import { TtlCache } from "./cache.js";
 import { stableStringify } from "./json.js";
 import { encodeProgramIdPath } from "./url.js";
+const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 60_000;
+const MAX_UPSTREAM_RATE_LIMIT_DELAY_MS = 10 * 60_000;
+const CHANGE_FEED_CONCURRENCY_LIMIT = 2;
+const TARGET_EXPORT_CONCURRENCY_LIMIT = 2;
+const UPSTREAM_KEY_IP_REQUEST_LIMIT = 60;
+const UPSTREAM_KEY_IP_WINDOW_MS = 60_000;
+const MAX_RESPONSE_BODY_BYTES = 16 * 1024 * 1024;
+const MAX_REQUEST_BODY_BYTES = 64 * 1024;
+const DEFAULT_PROGRAM_SWR_MS = 5 * 60_000;
+const DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 3;
+const DEFAULT_CIRCUIT_COOLDOWN_MS = 30_000;
 export class BBRadarApiError extends Error {
     requestId;
     upstreamRequestId;
     status;
     detail;
     errors;
+    cached;
+    coalesced;
+    cacheExpiresAt;
     constructor(params) {
         super(params.message, { cause: params.cause });
         this.name = "BBRadarApiError";
@@ -16,33 +30,98 @@ export class BBRadarApiError extends Error {
         this.status = params.status;
         this.detail = params.detail;
         this.errors = params.errors;
+        this.cached = params.cached ?? false;
+        this.coalesced = params.coalesced ?? false;
+        this.cacheExpiresAt = params.cacheExpiresAt;
     }
 }
 export class BBRadarClient {
     config;
     cache;
+    negativeCache;
     inFlight = new Map();
+    endpointMetrics = new Map();
+    requestQueue = [];
+    endpointRequestQueues = new Map();
+    endpointActiveRequests = new Map();
+    upstreamRateLimits = new Map();
+    circuitBreakers = new Map();
+    upstreamRequestTimestampsMs = [];
+    activeRequests = 0;
+    globalBlockedUntilMs;
+    capabilityNegotiation;
+    capabilityState = { status: "not_started" };
     constructor(config) {
         this.config = config;
-        this.cache = new TtlCache(config.cacheMaxEntries, config.cacheTtlMs);
+        this.cache = new TtlCache(config.cacheMaxEntries, config.cacheTtlMs, config.programStaleWhileRevalidateMs ?? DEFAULT_PROGRAM_SWR_MS);
+        this.negativeCache = new TtlCache(config.cacheMaxEntries, config.negativeCacheTtlMs);
     }
     diagnostics() {
+        const endpointEntries = [...this.endpointMetrics.entries()];
+        const totalRequests = endpointEntries.reduce((total, [, metric]) => total + metric.requests, 0);
+        const totalErrors = endpointEntries.reduce((total, [, metric]) => total + metric.errors, 0);
+        const totalMs = endpointEntries.reduce((total, [, metric]) => total + metric.totalMs, 0);
         return {
             response_cache: {
                 enabled: this.config.cacheTtlMs > 0 && this.config.cacheMaxEntries > 0,
                 ...this.cache.stats()
             },
-            in_flight_requests: this.inFlight.size
+            negative_response_cache: {
+                enabled: this.config.negativeCacheTtlMs > 0 && this.config.cacheMaxEntries > 0,
+                ...this.negativeCache.stats()
+            },
+            capability_negotiation: this.capabilitySnapshot(),
+            circuit_breakers: this.circuitBreakerDiagnostics(),
+            in_flight_requests: this.inFlight.size,
+            request_concurrency: {
+                limit: this.config.maxConcurrentRequests,
+                active: this.activeRequests,
+                queued: this.requestQueue.length,
+                endpoint_limits: {
+                    change_feeds: {
+                        limit: CHANGE_FEED_CONCURRENCY_LIMIT,
+                        active: this.endpointActiveRequests.get("change_feeds") ?? 0,
+                        queued: this.endpointRequestQueues.get("change_feeds")?.length ?? 0
+                    },
+                    target_export: {
+                        limit: TARGET_EXPORT_CONCURRENCY_LIMIT,
+                        active: this.endpointActiveRequests.get("target_export") ?? 0,
+                        queued: this.endpointRequestQueues.get("target_export")?.length ?? 0
+                    }
+                }
+            },
+            upstream_request_window: this.upstreamRequestWindowDiagnostics(),
+            upstream_rate_limit: this.upstreamRateLimitDiagnostics(),
+            upstream_requests: {
+                actual_requests: totalRequests,
+                errors: totalErrors,
+                avg_ms: totalRequests > 0 ? Math.round(totalMs / totalRequests) : 0,
+                max_ms: endpointEntries.reduce((maximum, [, metric]) => Math.max(maximum, metric.maxMs), 0),
+                by_endpoint: Object.fromEntries(endpointEntries.map(([endpoint, metric]) => [
+                    endpoint,
+                    {
+                        requests: metric.requests,
+                        errors: metric.errors,
+                        avg_ms: metric.requests > 0 ? Math.round(metric.totalMs / metric.requests) : 0,
+                        max_ms: metric.maxMs,
+                        last_ms: metric.lastMs,
+                        statuses: Object.fromEntries(metric.statuses)
+                    }
+                ]))
+            }
         };
     }
     async validateKey() {
         try {
-            await this.request({
-                path: "/pro/programs",
-                query: { page: 1, page_size: 1 },
-                cache: false,
-                coalesce: false
-            });
+            await this.negotiateCapabilities();
+            if (this.capabilityState.status === "legacy") {
+                await this.request({
+                    path: "/pro/programs",
+                    query: { page: 1, page_size: 1 },
+                    cache: false,
+                    coalesce: false
+                });
+            }
         }
         catch (error) {
             if (!(error instanceof BBRadarApiError)) {
@@ -63,26 +142,105 @@ export class BBRadarClient {
             throw error;
         }
     }
+    negotiateCapabilities() {
+        if (!this.capabilityNegotiation) {
+            this.capabilityNegotiation = this.fetchCapabilityContract();
+        }
+        return this.capabilityNegotiation;
+    }
+    capabilitySnapshot() {
+        return { ...this.capabilityState };
+    }
+    supportsEndpoint(endpoint) {
+        if (this.capabilityState.status !== "negotiated") {
+            return true;
+        }
+        const contract = asRecord(this.capabilityState.contract);
+        const endpoints = asRecord(contract?.endpoints);
+        return endpoints !== undefined && asRecord(endpoints[endpoint]) !== undefined;
+    }
+    endpointCapability(endpoint) {
+        if (this.capabilityState.status !== "negotiated") {
+            return undefined;
+        }
+        const contract = asRecord(this.capabilityState.contract);
+        return asRecord(asRecord(contract?.endpoints)?.[endpoint]);
+    }
+    endpointNumber(endpoint, field, fallback) {
+        const value = this.endpointCapability(endpoint)?.[field];
+        return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+    }
+    endpointStringArray(endpoint, field, fallback) {
+        const value = this.endpointCapability(endpoint)?.[field];
+        return Array.isArray(value) && value.every((entry) => typeof entry === "string")
+            ? [...value]
+            : [...fallback];
+    }
+    async fetchCapabilityContract() {
+        try {
+            const result = await this.getCapabilities({ cache: false, coalesce: false });
+            this.capabilityState = {
+                status: "negotiated",
+                negotiatedAt: result.fetchedAt,
+                contract: result.data
+            };
+        }
+        catch (error) {
+            if (error instanceof BBRadarApiError && (error.status === 404 || error.status === 405)) {
+                this.capabilityState = {
+                    status: "legacy",
+                    negotiatedAt: new Date().toISOString()
+                };
+                return;
+            }
+            this.capabilityState = {
+                status: "failed",
+                negotiatedAt: new Date().toISOString(),
+                error: error instanceof Error ? error.message : String(error)
+            };
+            throw error;
+        }
+    }
     listPrograms(query) {
         return this.request({
             path: "/pro/programs",
             query
         });
     }
+    getCapabilities(options = {}) {
+        return this.request({
+            path: "/pro/capabilities",
+            ...options
+        });
+    }
     getProgram(programId) {
         return this.request({
-            path: `/pro/programs/${encodeProgramIdPath(programId)}`
+            path: `/pro/programs/${encodeProgramIdPath(programId)}`,
+            staleWhileRevalidateMs: this.config.programStaleWhileRevalidateMs ?? DEFAULT_PROGRAM_SWR_MS
         });
     }
-    getProgramTargets(programId) {
+    getProgramTargets(programId, query = {}) {
         return this.request({
-            path: `/pro/programs/${encodeProgramIdPath(programId)}/targets`
+            path: `/pro/programs/${encodeProgramIdPath(programId)}/targets`,
+            query: {
+                page: 1,
+                page_size: this.endpointNumber("program_targets", "max_page_size", 500),
+                ...query
+            }
         });
     }
     getRecentChanges(query) {
         return this.request({
             path: "/pro/targets/changes",
-            query
+            query,
+            cache: query.after_id === undefined
+        });
+    }
+    getRepositoryChanges(query) {
+        return this.request({
+            path: "/pro/repositories/changes",
+            query,
+            cache: query.after_id === undefined
         });
     }
     searchTargets(query) {
@@ -116,18 +274,37 @@ export class BBRadarClient {
             body: options.body ?? null
         });
         const cacheable = method === "GET" && (options.cache ?? true) && this.config.cacheTtlMs > 0 && this.config.cacheMaxEntries > 0;
+        const negativeCacheable = method === "GET" &&
+            (options.cache ?? true) &&
+            this.config.negativeCacheTtlMs > 0 &&
+            this.config.cacheMaxEntries > 0;
         const coalesceable = method === "GET" && (options.coalesce ?? true);
         if (cacheable) {
-            const cached = this.cache.get(requestKey);
+            const cached = this.cache.getWithStale(requestKey, options.staleWhileRevalidateMs ?? 0);
             if (cached) {
+                if (cached.stale) {
+                    this.refreshInBackground(options, method, url, requestKey);
+                }
                 return {
                     ...cached.value,
                     requestId,
                     cached: true,
+                    stale: cached.stale,
                     cacheExpiresAt: new Date(cached.expiresAt).toISOString()
                 };
             }
         }
+        if (negativeCacheable) {
+            const cachedError = this.negativeCache.get(requestKey);
+            if (cachedError) {
+                throw new BBRadarApiError({
+                    ...cachedError.value,
+                    requestId,
+                    cached: true,
+                    cacheExpiresAt: new Date(cachedError.expiresAt).toISOString()
+                });
+            }
+        }
         if (coalesceable) {
             const pending = this.inFlight.get(requestKey);
             if (pending) {
@@ -141,7 +318,7 @@ export class BBRadarClient {
                     };
                 }
                 catch (error) {
-                    throw cloneApiError(error, requestId);
+                    throw cloneApiError(error, requestId, true);
                 }
             }
         }
@@ -154,12 +331,30 @@ export class BBRadarClient {
             if (cacheable) {
                 this.cache.set(requestKey, result);
             }
+            if (negativeCacheable) {
+                this.negativeCache.delete(requestKey);
+            }
             return {
                 ...result,
                 requestId,
                 cached: false
             };
         }
+        catch (error) {
+            if (negativeCacheable &&
+                error instanceof BBRadarApiError &&
+                error.status !== undefined &&
+                isNegativeCacheStatus(error.status)) {
+                this.negativeCache.set(requestKey, {
+                    message: error.message,
+                    upstreamRequestId: error.upstreamRequestId,
+                    status: error.status,
+                    detail: error.detail,
+                    errors: error.errors
+                });
+            }
+            throw error;
+        }
         finally {
             if (coalesceable) {
                 this.inFlight.delete(requestKey);
@@ -167,58 +362,430 @@ export class BBRadarClient {
         }
     }
     async fetchFromApi(options, method, url, requestId) {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
-        try {
-            const init = {
-                method,
-                headers: this.headers(options.body),
-                cache: "no-store",
-                signal: controller.signal
-            };
-            if (options.body !== undefined) {
-                init.body = JSON.stringify(options.body);
-            }
-            const response = await fetch(url, init);
-            const upstreamRequestId = extractRequestId(response.headers);
-            const data = await parseResponseBody(response);
-            if (!response.ok) {
-                const params = {
-                    message: formatApiErrorMessage(response.status, data),
+        const serializedBody = options.body === undefined ? undefined : JSON.stringify(options.body);
+        if (serializedBody !== undefined) {
+            const bodyBytes = Buffer.byteLength(serializedBody, "utf8");
+            if (bodyBytes > MAX_REQUEST_BODY_BYTES) {
+                throw new BBRadarApiError({
+                    message: `BBRadar API request body exceeds the ${MAX_REQUEST_BODY_BYTES}-byte limit.`,
                     requestId,
+                    status: 413,
+                    detail: { body_bytes: bodyBytes, max_body_bytes: MAX_REQUEST_BODY_BYTES }
+                });
+            }
+        }
+        return this.withRequestSlot(options.path, async () => {
+            const rateLimitBucket = rateLimitEndpointGroup(options.path);
+            this.assertCircuitClosed(requestId, rateLimitBucket);
+            this.reserveUpstreamRequest(requestId, rateLimitBucket);
+            const startedAt = Date.now();
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
+            let status;
+            let failed = true;
+            try {
+                const init = {
+                    method,
+                    headers: this.headers(options.body),
+                    signal: controller.signal
+                };
+                if (serializedBody !== undefined) {
+                    init.body = serializedBody;
+                }
+                const response = await fetch(url, init);
+                status = response.status;
+                this.observeCircuitResponse(rateLimitBucket, response.status);
+                this.observeUpstreamRateLimit(rateLimitBucket, response.headers, response.status);
+                const upstreamRequestId = extractRequestId(response.headers);
+                const data = await parseResponseBody(response);
+                if (!response.ok) {
+                    this.observeUpstreamErrorBody(rateLimitBucket, response.status, data);
+                    const params = {
+                        message: formatApiErrorMessage(response.status, data),
+                        requestId,
+                        status: response.status,
+                        detail: extractObjectField(data, "detail"),
+                        errors: extractObjectField(data, "errors")
+                    };
+                    if (upstreamRequestId) {
+                        params.upstreamRequestId = upstreamRequestId;
+                    }
+                    throw new BBRadarApiError(params);
+                }
+                const result = {
+                    data: data,
                     status: response.status,
-                    detail: extractObjectField(data, "detail"),
-                    errors: extractObjectField(data, "errors")
+                    fetchedAt: new Date().toISOString()
                 };
                 if (upstreamRequestId) {
-                    params.upstreamRequestId = upstreamRequestId;
+                    result.upstreamRequestId = upstreamRequestId;
                 }
-                throw new BBRadarApiError(params);
+                failed = false;
+                return result;
             }
-            const result = {
-                data: data,
-                status: response.status,
-                fetchedAt: new Date().toISOString()
-            };
-            if (upstreamRequestId) {
-                result.upstreamRequestId = upstreamRequestId;
+            catch (error) {
+                if (error instanceof BBRadarApiError) {
+                    throw error;
+                }
+                this.observeCircuitFailure(rateLimitBucket);
+                throw new BBRadarApiError({
+                    message: error instanceof Error && error.name === "AbortError" ? "BBRadar API request timed out." : "BBRadar API request failed.",
+                    requestId,
+                    cause: error
+                });
+            }
+            finally {
+                clearTimeout(timeout);
+                this.recordEndpointMetric(options.path, Date.now() - startedAt, status, failed);
             }
-            return result;
+        });
+    }
+    refreshInBackground(options, method, url, requestKey) {
+        if (this.inFlight.has(requestKey)) {
+            return;
         }
-        catch (error) {
-            if (error instanceof BBRadarApiError) {
-                throw error;
+        const refresh = this.fetchFromApi({ ...options, staleWhileRevalidateMs: 0 }, method, url, randomUUID());
+        this.inFlight.set(requestKey, refresh);
+        void refresh
+            .then((result) => {
+            this.cache.set(requestKey, result);
+            this.negativeCache.delete(requestKey);
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            if (this.inFlight.get(requestKey) === refresh) {
+                this.inFlight.delete(requestKey);
             }
-            throw new BBRadarApiError({
-                message: error instanceof Error && error.name === "AbortError" ? "BBRadar API request timed out." : "BBRadar API request failed.",
-                requestId,
-                cause: error
+        });
+    }
+    async withRequestSlot(path, callback) {
+        const endpointGroup = concurrencyEndpointGroup(path);
+        if (endpointGroup === undefined) {
+            return this.withGlobalRequestSlot(callback);
+        }
+        const endpointLimit = endpointConcurrencyLimit(endpointGroup);
+        if (endpointLimit === undefined) {
+            return this.withGlobalRequestSlot(callback);
+        }
+        return this.withEndpointRequestSlot(endpointGroup, endpointLimit, () => this.withGlobalRequestSlot(callback));
+    }
+    async withGlobalRequestSlot(callback) {
+        const limit = Math.max(1, this.config.maxConcurrentRequests);
+        if (this.activeRequests >= limit) {
+            await new Promise((resolve) => this.requestQueue.push(resolve));
+        }
+        else {
+            this.activeRequests += 1;
+        }
+        try {
+            return await callback();
+        }
+        finally {
+            const next = this.requestQueue.shift();
+            if (next) {
+                next();
+            }
+            else {
+                this.activeRequests -= 1;
+            }
+        }
+    }
+    async withEndpointRequestSlot(endpointGroup, limit, callback) {
+        const active = this.endpointActiveRequests.get(endpointGroup) ?? 0;
+        if (active >= limit) {
+            const queue = this.endpointRequestQueues.get(endpointGroup) ?? [];
+            await new Promise((resolve) => {
+                queue.push(resolve);
+                this.endpointRequestQueues.set(endpointGroup, queue);
             });
         }
+        else {
+            this.endpointActiveRequests.set(endpointGroup, active + 1);
+        }
+        try {
+            return await callback();
+        }
         finally {
-            clearTimeout(timeout);
+            const queue = this.endpointRequestQueues.get(endpointGroup);
+            const next = queue?.shift();
+            if (next) {
+                next();
+            }
+            else {
+                this.endpointActiveRequests.set(endpointGroup, Math.max(0, (this.endpointActiveRequests.get(endpointGroup) ?? 1) - 1));
+            }
+            if (queue?.length === 0) {
+                this.endpointRequestQueues.delete(endpointGroup);
+            }
+        }
+    }
+    recordEndpointMetric(path, durationMs, status, failed) {
+        const endpoint = metricEndpoint(path);
+        const metric = this.endpointMetrics.get(endpoint) ??
+            {
+                requests: 0,
+                errors: 0,
+                totalMs: 0,
+                maxMs: 0,
+                lastMs: 0,
+                statuses: new Map()
+            };
+        const statusKey = status === undefined ? "network_error" : String(status);
+        metric.requests += 1;
+        metric.errors += failed ? 1 : 0;
+        metric.totalMs += durationMs;
+        metric.maxMs = Math.max(metric.maxMs, durationMs);
+        metric.lastMs = durationMs;
+        metric.statuses.set(statusKey, (metric.statuses.get(statusKey) ?? 0) + 1);
+        this.endpointMetrics.set(endpoint, metric);
+    }
+    reserveUpstreamRequest(requestId, bucket) {
+        const now = Date.now();
+        const state = this.rateLimitState(bucket);
+        this.refreshUpstreamRateLimitWindow(state, now);
+        this.refreshUpstreamRequestWindow(now);
+        if ((this.globalBlockedUntilMs ?? 0) > now || (state.blockedUntilMs ?? 0) > now) {
+            throw localRateLimitError(requestId, bucket, state, this.globalBlockedUntilMs, this.upstreamRequestTimestampsMs.length);
+        }
+        if (this.shouldEnforceSharedRequestWindow() &&
+            this.upstreamRequestTimestampsMs.length >= UPSTREAM_KEY_IP_REQUEST_LIMIT) {
+            this.globalBlockedUntilMs =
+                (this.upstreamRequestTimestampsMs[0] ?? now) + UPSTREAM_KEY_IP_WINDOW_MS;
+            throw localRateLimitError(requestId, bucket, state, this.globalBlockedUntilMs, this.upstreamRequestTimestampsMs.length);
+        }
+        if (state.remaining !== undefined) {
+            if (state.remaining <= 0) {
+                state.blockedUntilMs =
+                    state.resetAtMs && state.resetAtMs > now
+                        ? state.resetAtMs
+                        : now + DEFAULT_RATE_LIMIT_COOLDOWN_MS;
+                throw localRateLimitError(requestId, bucket, state, this.globalBlockedUntilMs, this.upstreamRequestTimestampsMs.length);
+            }
+            state.remaining -= 1;
+        }
+        this.upstreamRequestTimestampsMs.push(now);
+    }
+    observeUpstreamRateLimit(bucket, headers, status) {
+        const now = Date.now();
+        const state = this.rateLimitState(bucket);
+        const limit = readRateLimitNumber(headers, ["x-ratelimit-limit", "ratelimit-limit"]);
+        const remaining = readRateLimitNumber(headers, ["x-ratelimit-remaining", "ratelimit-remaining"]);
+        const resetAtMs = parseRateLimitReset(headers, now);
+        const retryAtMs = parseRetryAfter(headers, now);
+        const previousResetAtMs = state.resetAtMs;
+        const sameWindow = resetAtMs === undefined ||
+            previousResetAtMs === undefined ||
+            Math.abs(resetAtMs - previousResetAtMs) < 1_000;
+        if (limit !== undefined) {
+            state.limit = limit;
+        }
+        if (remaining !== undefined) {
+            state.remaining =
+                sameWindow && state.remaining !== undefined
+                    ? Math.min(state.remaining, remaining)
+                    : remaining;
+        }
+        if (resetAtMs !== undefined) {
+            state.resetAtMs = resetAtMs;
+        }
+        state.observedAtMs = now;
+        state.lastStatus = status;
+        if (status === 429 || ((status === 423 || status === 503) && retryAtMs !== undefined)) {
+            const advertisedBlockUntil = Math.max(retryAtMs ?? 0, resetAtMs && resetAtMs > now ? resetAtMs : 0);
+            const blockedUntil = advertisedBlockUntil > now ? advertisedBlockUntil : now + DEFAULT_RATE_LIMIT_COOLDOWN_MS;
+            if (status === 429) {
+                state.remaining = 0;
+            }
+            state.blockedUntilMs = blockedUntil;
+            this.globalBlockedUntilMs = Math.max(this.globalBlockedUntilMs ?? 0, blockedUntil);
+            return;
+        }
+        if (remaining === 0) {
+            state.blockedUntilMs =
+                resetAtMs && resetAtMs > now ? resetAtMs : now + DEFAULT_RATE_LIMIT_COOLDOWN_MS;
+        }
+        else if ((state.blockedUntilMs ?? 0) <= now) {
+            state.blockedUntilMs = undefined;
+        }
+    }
+    observeUpstreamErrorBody(bucket, status, data) {
+        if (status !== 423) {
+            return;
+        }
+        const payload = asRecord(data);
+        const detail = asRecord(payload?.detail);
+        const rawLockedUntil = payload?.locked_until ?? detail?.locked_until;
+        if (typeof rawLockedUntil !== "string") {
+            return;
+        }
+        const parsed = Date.parse(rawLockedUntil);
+        if (!Number.isFinite(parsed) || parsed <= Date.now()) {
+            return;
+        }
+        const blockedUntil = Math.min(parsed, Date.now() + MAX_UPSTREAM_RATE_LIMIT_DELAY_MS);
+        const state = this.rateLimitState(bucket);
+        state.blockedUntilMs = Math.max(state.blockedUntilMs ?? 0, blockedUntil);
+        this.globalBlockedUntilMs = Math.max(this.globalBlockedUntilMs ?? 0, blockedUntil);
+    }
+    rateLimitState(bucket) {
+        const state = this.upstreamRateLimits.get(bucket) ?? {};
+        this.upstreamRateLimits.set(bucket, state);
+        return state;
+    }
+    refreshUpstreamRequestWindow(now) {
+        const cutoff = now - UPSTREAM_KEY_IP_WINDOW_MS;
+        while (this.upstreamRequestTimestampsMs.length > 0 &&
+            (this.upstreamRequestTimestampsMs[0] ?? now) <= cutoff) {
+            this.upstreamRequestTimestampsMs.shift();
+        }
+    }
+    upstreamRequestWindowDiagnostics() {
+        const now = Date.now();
+        this.refreshUpstreamRequestWindow(now);
+        const enforced = this.shouldEnforceSharedRequestWindow();
+        return {
+            enforced,
+            limit: UPSTREAM_KEY_IP_REQUEST_LIMIT,
+            window_ms: UPSTREAM_KEY_IP_WINDOW_MS,
+            used: this.upstreamRequestTimestampsMs.length,
+            remaining: enforced
+                ? Math.max(0, UPSTREAM_KEY_IP_REQUEST_LIMIT - this.upstreamRequestTimestampsMs.length)
+                : undefined,
+            resets_at: toIsoString(this.upstreamRequestTimestampsMs.length > 0
+                ? (this.upstreamRequestTimestampsMs[0] ?? now) + UPSTREAM_KEY_IP_WINDOW_MS
+                : undefined)
+        };
+    }
+    shouldEnforceSharedRequestWindow() {
+        try {
+            const hostname = new URL(this.config.apiBaseUrl).hostname.toLowerCase();
+            if (hostname === "bbradar.io" || hostname.endsWith(".bbradar.io")) {
+                return true;
+            }
+        }
+        catch {
+            // Invalid base URLs fail when a request URL is constructed.
+        }
+        return [...this.upstreamRateLimits.values()].some((state) => state.limit !== undefined ||
+            state.remaining !== undefined ||
+            state.resetAtMs !== undefined);
+    }
+    refreshUpstreamRateLimitWindow(state, now) {
+        if (state.resetAtMs !== undefined && state.resetAtMs <= now) {
+            state.remaining = undefined;
+            state.resetAtMs = undefined;
+        }
+        if (state.blockedUntilMs !== undefined && state.blockedUntilMs <= now) {
+            state.blockedUntilMs = undefined;
+        }
+    }
+    upstreamRateLimitDiagnostics() {
+        const now = Date.now();
+        const entries = [...this.upstreamRateLimits.entries()];
+        for (const [, state] of entries) {
+            this.refreshUpstreamRateLimitWindow(state, now);
+        }
+        if (this.globalBlockedUntilMs !== undefined && this.globalBlockedUntilMs <= now) {
+            this.globalBlockedUntilMs = undefined;
+        }
+        const observedEntries = entries.filter(([, state]) => state.observedAtMs !== undefined);
+        const latest = [...observedEntries].sort((left, right) => (right[1].observedAtMs ?? 0) - (left[1].observedAtMs ?? 0))[0];
+        const latestState = latest?.[1];
+        const globallyBlocked = (this.globalBlockedUntilMs ?? 0) > now;
+        const anyBucketBlocked = observedEntries.some(([, state]) => (state.blockedUntilMs ?? 0) > now);
+        const blockedUntil = Math.max(this.globalBlockedUntilMs ?? 0, ...observedEntries.map(([, state]) => state.blockedUntilMs ?? 0));
+        return {
+            observed: observedEntries.length > 0,
+            bucket: latest?.[0],
+            limit: latestState?.limit,
+            remaining: latestState?.remaining,
+            reset_at: toIsoString(latestState?.resetAtMs),
+            blocked: globallyBlocked || anyBucketBlocked,
+            globally_blocked: globallyBlocked,
+            blocked_until: toIsoString(blockedUntil > 0 ? blockedUntil : undefined),
+            observed_at: toIsoString(latestState?.observedAtMs),
+            last_status: latestState?.lastStatus,
+            buckets: Object.fromEntries(observedEntries.map(([bucket, state]) => [
+                bucket,
+                {
+                    limit: state.limit,
+                    remaining: state.remaining,
+                    reset_at: toIsoString(state.resetAtMs),
+                    blocked: (state.blockedUntilMs ?? 0) > now,
+                    blocked_until: toIsoString(state.blockedUntilMs),
+                    observed_at: toIsoString(state.observedAtMs),
+                    last_status: state.lastStatus
+                }
+            ]))
+        };
+    }
+    assertCircuitClosed(requestId, bucket) {
+        const state = this.circuitBreakers.get(bucket);
+        const now = Date.now();
+        if (!state?.openUntilMs || state.openUntilMs <= now) {
+            if (state?.openUntilMs !== undefined) {
+                state.openUntilMs = undefined;
+            }
+            return;
+        }
+        throw new BBRadarApiError({
+            message: `BBRadar ${bucket} circuit is temporarily open; no upstream request was sent.`,
+            requestId,
+            status: 503,
+            detail: {
+                source: "circuit_breaker",
+                bucket,
+                consecutive_failures: state.consecutiveFailures,
+                retry_at: new Date(state.openUntilMs).toISOString()
+            }
+        });
+    }
+    observeCircuitResponse(bucket, status) {
+        if (status >= 200 && status < 400) {
+            const state = this.circuitBreakers.get(bucket);
+            if (state) {
+                state.consecutiveFailures = 0;
+                state.openUntilMs = undefined;
+                state.lastSuccessAtMs = Date.now();
+                state.lastStatus = status;
+            }
+            return;
+        }
+        if (status === 423 || status === 429 || status >= 500) {
+            this.observeCircuitFailure(bucket, status);
         }
     }
+    observeCircuitFailure(bucket, status) {
+        const state = this.circuitBreakers.get(bucket) ?? { consecutiveFailures: 0 };
+        state.consecutiveFailures += 1;
+        state.lastFailureAtMs = Date.now();
+        state.lastStatus = status;
+        if (state.consecutiveFailures >=
+            (this.config.circuitBreakerFailureThreshold ?? DEFAULT_CIRCUIT_FAILURE_THRESHOLD)) {
+            state.openUntilMs =
+                Date.now() +
+                    (this.config.circuitBreakerCooldownMs ?? DEFAULT_CIRCUIT_COOLDOWN_MS);
+        }
+        this.circuitBreakers.set(bucket, state);
+    }
+    circuitBreakerDiagnostics() {
+        const now = Date.now();
+        return {
+            failure_threshold: this.config.circuitBreakerFailureThreshold ?? DEFAULT_CIRCUIT_FAILURE_THRESHOLD,
+            cooldown_ms: this.config.circuitBreakerCooldownMs ?? DEFAULT_CIRCUIT_COOLDOWN_MS,
+            by_endpoint: Object.fromEntries([...this.circuitBreakers.entries()].map(([bucket, state]) => [
+                bucket,
+                {
+                    state: (state.openUntilMs ?? 0) > now ? "open" : state.consecutiveFailures > 0 ? "closed_degraded" : "closed",
+                    consecutive_failures: state.consecutiveFailures,
+                    open_until: toIsoString(state.openUntilMs),
+                    last_failure_at: toIsoString(state.lastFailureAtMs),
+                    last_success_at: toIsoString(state.lastSuccessAtMs),
+                    last_status: state.lastStatus
+                }
+            ]))
+        };
+    }
     buildUrl(path, query) {
         const url = new URL(`${this.config.apiBaseUrl}${path}`);
         for (const [key, value] of Object.entries(query ?? {})) {
@@ -227,20 +794,19 @@ export class BBRadarClient {
             }
             if (Array.isArray(value)) {
                 if (value.length > 0) {
-                    url.searchParams.set(key, value.join(","));
+                    url.searchParams.set(key, [...value].map(String).sort().join(","));
                 }
                 continue;
             }
             url.searchParams.set(key, String(value));
         }
+        url.searchParams.sort();
         return url;
     }
     headers(body) {
         const headers = {
             authorization: `Bearer ${this.config.apiKey}`,
             accept: "application/json",
-            "cache-control": "no-cache, no-store, max-age=0",
-            pragma: "no-cache",
             "user-agent": "@bbradar/mcp"
         };
         if (body !== undefined) {
@@ -249,12 +815,155 @@ export class BBRadarClient {
         return headers;
     }
 }
+function localRateLimitError(requestId, bucket, state, globalBlockedUntilMs, upstreamWindowUsed) {
+    return new BBRadarApiError({
+        message: "BBRadar API quota is temporarily exhausted; no upstream request was sent.",
+        requestId,
+        status: 429,
+        detail: {
+            source: "local_rate_limit_guard",
+            bucket,
+            limit: state.limit,
+            remaining: state.remaining,
+            reset_at: toIsoString(state.resetAtMs),
+            retry_at: toIsoString(Math.max(state.blockedUntilMs ?? 0, globalBlockedUntilMs ?? 0)),
+            shared_key_ip_window: {
+                limit: UPSTREAM_KEY_IP_REQUEST_LIMIT,
+                used: upstreamWindowUsed,
+                remaining: Math.max(0, UPSTREAM_KEY_IP_REQUEST_LIMIT - upstreamWindowUsed)
+            }
+        }
+    });
+}
+function readRateLimitNumber(headers, names) {
+    for (const name of names) {
+        const value = headers.get(name);
+        if (value === null) {
+            continue;
+        }
+        const parsed = Number(value.trim());
+        if (Number.isFinite(parsed) && parsed >= 0) {
+            return Math.floor(parsed);
+        }
+    }
+    return undefined;
+}
+function parseRateLimitReset(headers, now) {
+    const value = headers.get("x-ratelimit-reset") ?? headers.get("ratelimit-reset");
+    if (!value) {
+        return undefined;
+    }
+    const numeric = Number(value.trim());
+    if (Number.isFinite(numeric) && numeric >= 0) {
+        if (numeric >= 1_000_000_000_000) {
+            return boundUpstreamRateLimitTimestamp(numeric, now);
+        }
+        if (numeric >= 1_000_000_000) {
+            return boundUpstreamRateLimitTimestamp(numeric * 1_000, now);
+        }
+        return boundUpstreamRateLimitTimestamp(now + numeric * 1_000, now);
+    }
+    const timestamp = Date.parse(value);
+    return boundUpstreamRateLimitTimestamp(timestamp, now);
+}
+function parseRetryAfter(headers, now) {
+    const value = headers.get("retry-after");
+    if (!value) {
+        return undefined;
+    }
+    const seconds = Number(value.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return boundUpstreamRateLimitTimestamp(now + seconds * 1_000, now);
+    }
+    const timestamp = Date.parse(value);
+    return boundUpstreamRateLimitTimestamp(timestamp, now);
+}
+function boundUpstreamRateLimitTimestamp(timestamp, now) {
+    if (!Number.isFinite(timestamp)) {
+        return undefined;
+    }
+    return Math.min(timestamp, now + MAX_UPSTREAM_RATE_LIMIT_DELAY_MS);
+}
+function toIsoString(timestamp) {
+    if (timestamp === undefined || !Number.isFinite(timestamp)) {
+        return undefined;
+    }
+    const date = new Date(timestamp);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+function metricEndpoint(path) {
+    if (/^\/pro\/programs\/.+\/targets$/.test(path)) {
+        return "/pro/programs/:program_id/targets";
+    }
+    if (/^\/pro\/programs\/.+/.test(path)) {
+        return "/pro/programs/:program_id";
+    }
+    if (/^\/pro\/opportunities\/[^/]+$/.test(path)) {
+        return "/pro/opportunities/:level";
+    }
+    return path;
+}
+function rateLimitEndpointGroup(path) {
+    if (path === "/pro/targets/changes") {
+        return "change_feeds";
+    }
+    if (path === "/pro/repositories/changes") {
+        return "change_feeds";
+    }
+    if (/^\/pro\/programs\/.+\/targets$/.test(path)) {
+        return "target_operations";
+    }
+    if (path === "/pro/capabilities" ||
+        path === "/pro/programs" ||
+        /^\/pro\/programs\/.+/.test(path) ||
+        /^\/pro\/opportunities\/[^/]+$/.test(path)) {
+        return "programs_and_opportunities";
+    }
+    if (path === "/pro/targets/search") {
+        return "target_operations";
+    }
+    if (path === "/pro/targets/export") {
+        return "target_operations";
+    }
+    return "other";
+}
+function concurrencyEndpointGroup(path) {
+    if (path === "/pro/targets/changes" || path === "/pro/repositories/changes") {
+        return "change_feeds";
+    }
+    if (path === "/pro/targets/export") {
+        return "target_export";
+    }
+    return undefined;
+}
+function endpointConcurrencyLimit(endpointGroup) {
+    if (endpointGroup === "change_feeds") {
+        return CHANGE_FEED_CONCURRENCY_LIMIT;
+    }
+    if (endpointGroup === "target_export") {
+        return TARGET_EXPORT_CONCURRENCY_LIMIT;
+    }
+    return undefined;
+}
+function isNegativeCacheStatus(status) {
+    return status === 404 || status === 405;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
 async function parseResponseBody(response) {
     if (response.status === 204) {
         return null;
     }
     const contentType = response.headers.get("content-type") ?? "";
-    const text = await response.text();
+    const advertisedLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(advertisedLength) && advertisedLength > MAX_RESPONSE_BODY_BYTES) {
+        await response.body?.cancel();
+        throw new Error("BBRadar API response exceeded the MCP response-size limit.");
+    }
+    const text = await readBoundedResponseText(response, MAX_RESPONSE_BODY_BYTES);
     if (text.length === 0) {
         return null;
     }
@@ -268,6 +977,34 @@ async function parseResponseBody(response) {
     }
     return text;
 }
+async function readBoundedResponseText(response, maxBytes) {
+    if (!response.body) {
+        return "";
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let totalBytes = 0;
+    let text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            totalBytes += value.byteLength;
+            if (totalBytes > maxBytes) {
+                await reader.cancel();
+                throw new Error("BBRadar API response exceeded the MCP response-size limit.");
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+        text += decoder.decode();
+        return text;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 function extractRequestId(headers) {
     return (headers.get("x-request-id") ??
         headers.get("x-correlation-id") ??
@@ -290,7 +1027,7 @@ function formatApiErrorMessage(status, data) {
             : "Request was rejected.";
     return `BBRadar API returned ${status}: ${suffix}`;
 }
-function cloneApiError(error, requestId) {
+function cloneApiError(error, requestId, coalesced = error instanceof BBRadarApiError && error.coalesced) {
     if (!(error instanceof BBRadarApiError)) {
         return error;
     }
@@ -301,6 +1038,9 @@ function cloneApiError(error, requestId) {
         status: error.status,
         detail: error.detail,
         errors: error.errors,
+        cached: error.cached,
+        coalesced,
+        cacheExpiresAt: error.cacheExpiresAt,
         cause: error
     });
 }