@bbradar/mcp 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Release notes
+
+## 0.2.6 — expanded Pro API
+
+- Added seven direct tools for semantic History, exact program activity, and daily analytics, using one data request per page and lazy change detail.
+- Added `program_kind` filtering and source-classified contest discovery. Program projections now retain schedule precision, lifecycle state, fee metadata, Self-Hosted verification, and archive/catalog identity.
+- Preserved the distinct pagination models: numeric target/repository bookmarks, stable snapshot tokens, and five-minute opaque History/analytics cursors. Snapshot continuation now advances pages without mixing tokens.
+- Routed new reads through the existing shared changes quota and two-request concurrency pool. Added a 100-request queue ceiling and a total request deadline that includes queue time.
+- Connected MCP cancellation and a total tool deadline to HTTP requests, including compatibility with Node 20.0.0. Cancelling one caller preserves an in-flight request needed by another caller; unused work is aborted without opening the circuit breaker.
+- Preserved explicit unknown fee, report-count, and scoring values in compact results, and kept case-sensitive program IDs distinct in fallback caches.
+- Scoped persisted numeric feed checkpoints to the API destination and credential. Existing 0.2.5 persisted streams need one explicit `after_id` seed after upgrading.
+- Honored upstream `private` and `no-store` on success and error caches, including stale refreshes. Private results are not kept in local continuation or export resources.
+- Added deterministic route, schema, privacy, package-installation, and benchmark coverage.

package/README.md

@@ -1,6 +1,6 @@
 # @bbradar/mcp
 
-Local STDIO MCP server for [bbradar.io](https://bbradar.io) Pro subscribers. It lets MCP clients query [bbradar.io](https://bbradar.io) platform and Self-Hosted program profiles, active targets, target-level opportunity intelligence, recent target changes, and repository-change events through a local npm package.
+Local STDIO MCP server for [bbradar.io](https://bbradar.io) Pro subscribers. It exposes program and target discovery, semantic History, exact activity, daily analytics, and repository-change events through a local npm package.
 
 ## Requirements
 
@@ -115,6 +115,7 @@ Most tools that accept `program_id` also accept a human program name or handle.
 Self-Hosted programs use IDs such as `Self-Hosted:program-slug`. They are available through program search, exact program detail, reverse target search, program-target tools, and the normal `find_hunt_targets` ranking path. Their `data_capabilities` field identifies unavailable source signals; the MCP server does not invent opportunity scores, public report counts, target-change history, submission costs, repository changes, or numeric competition evidence for that catalog. A Self-Hosted-only hunt skips the unsupported target-change feed and derives recent-target evidence from current inventory timestamps. A Self-Hosted-only repository hunt returns immediately with guidance instead of spending upstream requests on an unsupported feed; mixed repository hunts omit Self-Hosted and continue with supported platforms.
 
 `search_programs` accepts a `search` value and sends it to the API for indexed server-side filtering. Name resolution uses the same path automatically, avoiding broad page scans for exact or partial program names.
+Use `program_kind: "bounty"`, `"contest"`, or `"challenge"` with `search_programs` or `find_programs` for source-classified program filtering. `find_web3_contests` uses this classification instead of inferring contests from a name or platform.
 The program catalog now includes confirmed paused platform programs. Raw search preserves `program_status` and `is_active`; ranked discovery excludes paused programs so retained scope and historical rewards cannot be presented as huntable. Exact paused-program reads remain available when explicitly requested.
 
 The full tool profile also exposes `search_targets`, a one-request low-level wrapper for reverse search and paginated current target inventory. It supports optional `q`, all API match modes, platform/tag filters, eligibility controls, pages up to the negotiated 500-row limit, and compact or full target output.
@@ -122,7 +123,7 @@ The full tool profile also exposes `search_targets`, a one-request low-level wra
 `find_programs_by_target` defaults to flexible target matching. It accepts bare domains, full URLs, wildcard scopes, target names, package/repo-style identifiers, or short phrases like `known api target`.
 It uses the Pro API's direct reverse-target-search route first, including for Self-Hosted targets, and only falls back to sampled target lists when an older API deployment does not expose that route.
 
-`export_targets` uses the bounded bearer `POST /api/v1/pro/targets/export` route directly. JSON exports preserve `program_id` on every target; CSV previews are capped in the tool result while the complete payload remains available for ten minutes through the returned `bbradar://exports` resource. The local resource store is capped at 25 entries and 64 MiB in aggregate, and CSV formula/control-byte neutralization is applied independently of the API.
+`export_targets` uses the bounded bearer `POST /api/v1/pro/targets/export` route directly. JSON exports preserve `program_id` on every target. When the API marks a response private or `no-store`, the complete sanitized export is returned only in the current structured tool result; it is not saved to a reusable resource. For responses that permit storage, the complete payload remains available for ten minutes through `bbradar://exports`. The local resource store is capped at 25 entries and 64 MiB in aggregate, and CSV formula/control-byte neutralization is applied independently of the API.
 
 `get_program_targets` forwards text, target type, eligibility, minimum Target Opportunity Score, Target Opportunity Label, and competition-risk filters to the API. Compact output retains the score, label, competition risk, and Why This Target; full output also includes the score breakdown and reason fields.
 When no local scope filtering is needed, offsets begin at the corresponding upstream
@@ -134,6 +135,28 @@ Repository results preserve the API's comparison completeness/method/ancestry ev
 
 `search_programs`, `search_targets`, `get_recent_changes`, and `get_repository_changes` accept the API's optional stable `snapshot` token. Send `snapshot: "start"` on page 1 and reuse the returned `meta.snapshot` with identical filters until `meta.snapshot_expires_at`. Snapshot responses bypass the local TTL cache, and an expired snapshot 410 is not mistaken for an expired change-feed cursor. Snapshot creation receives a 60-second minimum request timeout because it performs consistency work and can be materially slower; the fast `find_hunt_targets` workflow intentionally keeps live indexed paging and the ordinary configured timeout.
 
+### Pro History and analytics
+
+The `2026-09-24` API contract maps to these direct MCP tools. Each call reads one page unless the caller explicitly supplies a cursor for the next page. Change detail is fetched only when requested.
+
+| Pro API route | MCP tool | Page default |
+| --- | --- | ---: |
+| `GET /v1/pro/history/changes` | `get_history_changes` | 50 |
+| `GET /v1/pro/history/changes/{change_id}` | `get_history_change_detail` | 50 |
+| `GET /v1/pro/history/programs/{program_id}` | `get_program_history` | 50 |
+| `GET /v1/pro/activity/programs/{program_id}` | `get_program_activity` | one summary |
+| `GET /v1/pro/analytics/platforms/{platform}/series` | `get_analytics_platform_series` | 100 days |
+| `GET /v1/pro/analytics/programs/activity` | `get_analytics_program_activity` | 50 programs |
+| `GET /v1/pro/analytics/programs/{program_id}` | `get_analytics_program_detail` | 100 days |
+
+History defaults to 90 days; `days: 0` requests all retained History for an exact program. Use the scoped `get_program_history` route for `Self-Hosted:slug` IDs. A History response contains `coverage`, `tracking_since`, `observed_at`, `published_at`, and `provider_revision`; an empty `changes` array with `capture_enabled: false` means unavailable capture rather than a confirmed absence of changes. `catalog_id` identifies a Self-Hosted catalog record for later catalog reads, while `id` preserves the archive identity. Program IDs with slashes, literal percent signs, and case distinctions are preserved.
+
+Analytics dates are inclusive UTC `YYYY-MM-DD`. Omit both dates for the API's latest 90-day interval. The daily retention window is 36 calendar months. The category ranking supports `all`, `scope`, `rewards`, `rules`, `schedule`, `costs`, and `lifecycle`; repository metrics remain unsupported. Inspect `model_version`, `generation`, `projection_pending`, `provisional`, `unsupported_metrics`, and observation coverage. A carried inventory state is not a fresh source verification, and `null` is not measured zero. Use `get_analytics_program_activity` for server-side activity ranking; the program-list API has no activity sort. Other client-side rankings remain bounded samples, not complete catalog sorts.
+
+For example, call `get_program_history` with `{ "program_id": "Self-Hosted:program-slug", "days": 90, "limit": 50 }`, then pass `meta.next_cursor` back with the same arguments for the next page. Call `get_history_change_detail` with a returned change ID only when before/after items are needed. `get_program_activity` reads the exact `activity_summary`; `summarize_program_activity` keeps its target-change samples explicitly separate from semantic History.
+
+History and analytics cursors are signed, opaque, and expire after five minutes. Reuse them with the same filters and page size; never persist them as numeric feed checkpoints. On 410, restart an expired History or analytics query, start a new snapshot for an expired snapshot token, reconcile inventory for a retained numeric-feed gap, or choose supported analytics dates when outside retention. Do not combine pages from different snapshots or analytics generations. The target-change feed describes latest retained state and is not a complete immutable event journal.
+
 If a cursor predates retained API history, the MCP refreshes the relevant current
 target or repository-change inventory within the same page/time bounds. It advances to a new
 baseline only after the bounded inventory completes and unchanged feed probes prove
@@ -152,11 +175,11 @@ inventory ends. Missing public scope is treated as out of scope.
 
 Cursors are memory-only by default. Set `BBRADAR_MCP_CURSOR_STATE_PATH` to opt into restart-safe cursor persistence. The state file contains only endpoint-prefixed SHA-256 filter hashes and non-negative numeric IDs—never raw filters, API responses, program or target records, credentials, or authorization headers.
 
-Large target and change collections return at most 50 inline records by default. The remainder is held in a bounded, ten-minute in-memory continuation and exposed through a `bbradar://continuations` resource link. This keeps model context small without losing access to the complete bounded result.
+For cacheable responses, large target and change collections return at most 50 inline records by default; the remainder is held in a bounded, ten-minute continuation resource. Private or `no-store` pages stay in the current structured result and are never put in a reusable continuation. Compact tool text keeps model context small.
 
 ## Performance Tuning
 
-The defaults expose the 18-tool core surface and compact text results while enabling bounded concurrency, positive response caching, in-flight request coalescing, stale-while-revalidate program metadata, endpoint circuit breakers, and short negative caching for repeated 404/405 lookups. Set the tool profile to `full` when all specialized tools are needed.
+The defaults expose the 25-tool core surface and compact text results while enabling bounded concurrency, in-flight request coalescing, endpoint circuit breakers, and response caching only when upstream cache policy permits it. The Pro deployment currently sends `private, no-store`, so its responses are not placed in the reusable response cache or stale-while-revalidate cache. Set the tool profile to `full` when all specialized tools are needed.
 
 | Environment variable | Default | Purpose |
 | --- | ---: | --- |
@@ -164,9 +187,9 @@ The defaults expose the 18-tool core surface and compact text results while enab
 | `BBRADAR_MCP_NEGATIVE_CACHE_TTL_SECONDS` | `15` | Repeated 404/405 cache lifetime. Set to `0` to disable. |
 | `BBRADAR_MCP_CACHE_MAX_ENTRIES` | `500` | Maximum entries in each local response cache. |
 | `BBRADAR_MCP_MAX_CONCURRENT_REQUESTS` | `6` | Maximum simultaneous upstream BBRadar API requests. |
-| `BBRADAR_MCP_REQUEST_TIMEOUT_SECONDS` | `30` | Timeout for each active upstream request; queue time is excluded. |
+| `BBRADAR_MCP_REQUEST_TIMEOUT_SECONDS` | `30` | Total upstream request deadline, including queue time. |
 | `BBRADAR_MCP_COMPACT_TOOL_TEXT` | `true` | Avoid duplicating full results for clients that consume MCP `structuredContent`. Set to `false` for legacy text-only clients. |
-| `BBRADAR_MCP_TOOL_PROFILE` | `core` | Compact 18-tool discovery surface. Set to `full` for every specialized tool. |
+| `BBRADAR_MCP_TOOL_PROFILE` | `core` | Compact 25-tool discovery surface. Set to `full` for every specialized tool. |
 | `BBRADAR_MCP_PROGRAM_STALE_WHILE_REVALIDATE_SECONDS` | `300` | Maximum stale window for exact program metadata while one background refresh runs. |
 | `BBRADAR_MCP_CIRCUIT_BREAKER_FAILURE_THRESHOLD` | `3` | Consecutive retryable endpoint failures before its circuit opens. |
 | `BBRADAR_MCP_CIRCUIT_BREAKER_COOLDOWN_SECONDS` | `30` | Endpoint circuit cooldown before a new request is admitted. |
@@ -175,15 +198,23 @@ The defaults expose the 18-tool core surface and compact text results while enab
 | `BBRADAR_MCP_CONTINUATION_TTL_SECONDS` | `600` | Lifetime of in-memory continuation results. |
 | `BBRADAR_MCP_ALLOW_INSECURE_HTTP` | `false` | Explicitly allow an HTTP API base URL outside loopback for a trusted private development network. Never enable for internet traffic. |
 
-No performance variables are required. Capability-derived page limits and snapshot support, caching, request coalescing, server-side name resolution, reverse-target search, early stopping, bounded concurrency, aggregate-call parallelism, a 64 KiB request-body ceiling, a 16 MiB upstream response ceiling, automatic HTTP compression handling, connection reuse, and upstream quota protection are always active. Unsupported capability-gated tools are removed from discovery. Target responses expose upstream pagination state so an AI client does not mistake a capped page for a complete inventory.
+No performance variables are required. Capability-derived page limits and snapshot support, cache-policy-aware caching, request coalescing, server-side name resolution, reverse-target search, early stopping, bounded concurrency and queues, aggregate-call parallelism, a 64 KiB request-body ceiling, a 16 MiB upstream response ceiling, automatic HTTP compression handling, connection reuse, and upstream quota protection are always active. Target responses expose upstream pagination state so an AI client does not mistake a capped page for a complete inventory.
 
-The client learns the API's `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers per endpoint group. Once an observed group reaches zero, it blocks additional requests to that group locally until reset instead of repeatedly hitting the API, while unrelated endpoint groups remain usable. Target and repository changes share one quota state and one conservative two-request concurrency pool. A rolling 60-second guard also enforces the documented shared key-and-IP ceiling across uncached upstream requests. Real `423`, `429`, and `503` responses honor `Retry-After` as a local cooldown, capped at ten minutes so a malformed upstream header cannot lock the MCP process indefinitely. Requests are not automatically retried, so one MCP action cannot amplify an admission or rate-limit response into more API calls. The global upstream concurrency default is six and bulk exports are capped at two; cursor page walking is strictly sequential.
+The client learns the API's `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers per endpoint group. Once an observed group reaches zero, it blocks additional requests to that group locally until reset instead of repeatedly hitting the API, while unrelated endpoint groups remain usable. Target changes, repository changes, History, exact activity, and analytics share one quota state and one conservative two-request concurrency pool. A rolling 60-second guard also enforces the documented shared key-and-IP ceiling across uncached upstream requests. Real `423`, `429`, and `503` responses honor `Retry-After` as a local cooldown, capped at ten minutes so a malformed upstream header cannot lock the MCP process indefinitely. Requests are not automatically retried. The global upstream concurrency default is six, each queue is capped at 100, and bulk exports are capped at two.
 
 The bearer API destination must use HTTPS. Loopback HTTP remains available for local development; non-loopback HTTP requires the explicit `BBRADAR_MCP_ALLOW_INSECURE_HTTP=true` opt-in. API base URLs containing embedded credentials, query strings, fragments, or non-HTTP schemes are rejected before the key can be sent.
 
 Call `get_mcp_status` to inspect cache and stale-hit rates, circuit states, cursor persistence, concurrency, negotiated capabilities, upstream quotas, actual request counts, per-endpoint status totals, and timing.
 
-Run `npm run benchmark` for the deterministic local performance benchmark. It reports request and byte reductions for reverse target discovery, exact-program cache efficiency, and context reduction from bounded continuations.
+Run `npm run benchmark` for deterministic local benchmarks. They report request and byte counts, model-context bytes, latency percentiles, and memory under representative History and analytics concurrency. Fixture timings are separate from live API latency.
+
+Maintainers can compare the working tree against a committed revision with `npm run build` followed by `node --expose-gc benchmark/compare-revisions.mjs HEAD`. This uses the same fixtures and alternating samples for both revisions, reports discovery and result sizes, and measures repeated private reads separately from cacheable reads. It requires the repository and development dependencies.
+
+Run `npm run test:package` to pack the release, install its production dependencies in a temporary directory, audit them, and exercise the packaged STDIO server. CI runs the checks on Node 20, 22, and 24.
+
+MCP cancellation reaches active and queued HTTP work. Each tool shares one total deadline across its requests, using `BBRADAR_MCP_REQUEST_TIMEOUT_SECONDS`; snapshot creation keeps its 60-second minimum. Identical concurrent GETs can share one upstream request, and cancelling one caller preserves it while another caller still needs it.
+
+Persisted numeric feed checkpoints are scoped to the API destination and credential. When upgrading from 0.2.5, seed each persisted stream once with `after_id` before using `resume_cursor`; old unscoped checkpoints are not reused.
 
 ### Flexible multi-signal discovery
 
@@ -234,6 +265,13 @@ This path uses one recent-changes request. Use `find_wildcard_programs` for a ra
 - `get_program_targets`
 - `get_recent_changes`
 - `get_repository_changes`
+- `get_history_changes`
+- `get_history_change_detail`
+- `get_program_history`
+- `get_program_activity`
+- `get_analytics_platform_series`
+- `get_analytics_program_activity`
+- `get_analytics_program_detail`
 - `find_hunt_targets`
 - `find_repository_hunt_targets`
 - `get_opportunities`

package/benchmark/compare-revisions.mjs

@@ -0,0 +1,164 @@
+// Maintainer check: npm run build && node --expose-gc benchmark/compare-revisions.mjs [git-ref]
+// Compiles a read-only source snapshot in a temporary directory; leaves the checkout untouched.
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import ts from "typescript";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { BBRadarClient } from "../dist/bbradarClient.js";
+import { createBbradarServer } from "../dist/server.js";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const ref = process.argv[2] ?? "HEAD";
+const baselineCommit = execFileSync("git", ["rev-parse", "--verify", `${ref}^{commit}`], { cwd: root, encoding: "utf8" }).trim();
+const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "bbradar-compare-"));
+const counts = { requests: 0, bytes: 0, active: 0, peak: 0 };
+const now = new Date().toISOString();
+const programs = Array.from({ length: 100 }, (_, i) => ({
+  id: `Platform:program-${i}`, handle: `program-${i}`, name: `Program ${i}`, platform: "Platform",
+  program_kind: "bounty", is_active: true, scope_tags: ["domain", "api", "wildcard"],
+  added_at: now, last_updated: now, bounty_min: 100, bounty_max: 5000 + i * 100, report_count: i,
+  target_counts: { total: 20, in_scope: 20, eligible_for_bounty: 20, wildcard: 2 },
+  target_activity: { latest_change_at: now, added_24h: 1, added_7d: 2 }
+}));
+const targets = Array.from({ length: 20 }, (_, i) => ({
+  identifier: `api-${i}.example`, target_type: "domain", in_scope: true, eligible_for_bounty: true,
+  wildcard: i < 2, targetOpportunityScore: 75, targetOpportunityLabel: "Strong Target", competitionRisk: "Low",
+  scoreVersion: 3, evidenceCoverage: { source: "verified" }, targetScoreBreakdown: { scope: 30, freshness: 20 }
+}));
+let cacheControl = "private, no-store";
+const api = http.createServer(async (req, res) => {
+  counts.requests += 1;
+  counts.active += 1;
+  counts.peak = Math.max(counts.peak, counts.active);
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  const url = new URL(req.url, "http://fixture");
+  const endpoint = url.pathname.replace(/^\/api\/v1/, "");
+  let payload;
+  if (endpoint === "/pro/programs") payload = { programs: programs.slice(0, Number(url.searchParams.get("page_size") ?? 100)), meta: { total_pages: 1 } };
+  else if (endpoint.endsWith("/targets")) payload = { targets, meta: { total: 20, total_pages: 1 } };
+  else if (endpoint.startsWith("/pro/programs/")) payload = programs[0];
+  else if (endpoint === "/pro/targets/search") payload = { results: [{ program: programs[0], target: targets[0] }], meta: { has_more: false } };
+  else if (endpoint === "/pro/targets/changes") payload = { results: programs.slice(0, 10).map((program, i) => ({ id: i + 1, program, target: targets[i], change_type: "added", changed_at: now })), meta: { total_pages: 1, has_more: false } };
+  else { res.statusCode = 404; payload = { detail: "missing fixture route" }; }
+  const body = JSON.stringify(payload);
+  counts.bytes += Buffer.byteLength(body);
+  res.setHeader("content-type", "application/json");
+  res.setHeader("cache-control", cacheControl);
+  res.end(body);
+  counts.active -= 1;
+});
+const sessions = [];
+const reset = () => { counts.requests = 0; counts.bytes = 0; counts.peak = 0; };
+const round = (n) => Math.round(n * 100) / 100;
+function percentile(values, p) { return [...values].sort((a, b) => a - b)[Math.ceil(values.length * p) - 1]; }
+
+try {
+  fs.writeFileSync(path.join(temporary, "package.json"), '{"type":"module"}');
+  fs.symlinkSync(path.join(root, "node_modules"), path.join(temporary, "node_modules"), "junction");
+  const sources = execFileSync("git", ["ls-tree", "-r", "--name-only", baselineCommit, "src"], { cwd: root, encoding: "utf8" }).trim().split(/\r?\n/).filter((name) => name.endsWith(".ts"));
+  for (const source of sources) {
+    const input = execFileSync("git", ["show", `${baselineCommit}:${source}`], { cwd: root, encoding: "utf8" });
+    const output = ts.transpileModule(input, { compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext } }).outputText;
+    fs.writeFileSync(path.join(temporary, path.basename(source, ".ts") + ".js"), output);
+  }
+  const baselineClient = (await import(pathToFileURL(path.join(temporary, "bbradarClient.js")))).BBRadarClient;
+  const baselineServer = (await import(pathToFileURL(path.join(temporary, "server.js")))).createBbradarServer;
+  await new Promise((resolve) => api.listen(0, "127.0.0.1", resolve));
+  const config = {
+    apiKey: "fixture", apiBaseUrl: `http://127.0.0.1:${api.address().port}/api/v1`, webBaseUrl: "https://bbradar.io",
+    cacheTtlMs: 0, negativeCacheTtlMs: 0, cacheMaxEntries: 500, maxConcurrentRequests: 6,
+    defaultRateLimitPerMinute: 10000, exportRateLimitPerMinute: 10000,
+    compactToolText: true, toolProfile: "core", requestTimeoutMs: 5000, validateOnStartup: false
+  };
+  async function connect(ClientType, createServer) {
+    const upstream = new ClientType(config);
+    const server = createServer(upstream, config);
+    const client = new Client({ name: "revision-benchmark", version: "1" });
+    const [a, b] = InMemoryTransport.createLinkedPair();
+    await Promise.all([server.connect(b), client.connect(a)]);
+    const session = { client, server, upstream };
+    sessions.push(session);
+    return session;
+  }
+  const pair = [await connect(baselineClient, baselineServer), await connect(BBRadarClient, createBbradarServer)];
+  const workflows = [
+    ["search_programs", { page_size: 20 }],
+    ["get_program_targets", { program_id: "Platform:program-0", limit: 20 }],
+    ["find_programs", { platforms: ["Platform"], max_pages: 1, max_results: 10, include_target_samples: false }],
+    ["get_recent_changes", { page_size: 10 }],
+    ["find_hunt_targets", { platforms: ["Platform"], max_program_pages: 1, max_results: 10, targets_per_result: 5, upstream_request_budget: 20 }]
+  ];
+  const report = {};
+  for (const [name, args] of workflows) {
+    // Warm code and connections, then alternate revision order to reduce order bias.
+    for (const session of pair) for (let i = 0; i < 3; i += 1) await session.client.callTool({ name, arguments: args });
+    const samples = [[], []];
+    for (let i = 0; i < 30; i += 1) for (const index of i % 2 ? [1, 0] : [0, 1]) {
+      reset();
+      const started = performance.now();
+      const result = await pair[index].client.callTool({ name, arguments: args });
+      assert.equal(result.isError, undefined, `${name} revision ${index}`);
+      samples[index].push({ ms: performance.now() - started, requests: counts.requests, upstream_bytes: counts.bytes,
+        model_text_bytes: Buffer.byteLength(result.content[0].text), structured_bytes: Buffer.byteLength(JSON.stringify(result.structuredContent)) });
+    }
+    const summaries = samples.map((rows) => ({
+      samples: rows.length, requests_per_call: rows[0].requests, upstream_bytes: rows[0].upstream_bytes,
+      model_text_bytes: rows[0].model_text_bytes, structured_bytes: rows[0].structured_bytes,
+      p50_ms: round(percentile(rows.map((x) => x.ms), .5)), p95_ms: round(percentile(rows.map((x) => x.ms), .95))
+    }));
+    assert.equal(summaries[0].requests_per_call, summaries[1].requests_per_call, `${name}: upstream request regression`);
+    report[name] = { baseline: summaries[0], candidate: summaries[1], p50_change_percent: round((summaries[1].p50_ms / summaries[0].p50_ms - 1) * 100) };
+  }
+  const repeated = {};
+  for (const policy of ["public, max-age=30", "private, no-store"]) {
+    cacheControl = policy;
+    repeated[policy] = [];
+    for (const ClientType of [baselineClient, BBRadarClient]) {
+      const upstream = new ClientType({ ...config, cacheTtlMs: 30000 });
+      reset();
+      const started = performance.now();
+      for (let i = 0; i < 20; i += 1) await upstream.getProgram("Platform:program-0");
+      repeated[policy].push({ calls: 20, requests: counts.requests, duration_ms: round(performance.now() - started) });
+    }
+  }
+  cacheControl = "private, no-store";
+  const concurrency = [];
+  for (const session of pair) {
+    global.gc?.();
+    const heap = process.memoryUsage().heapUsed;
+    reset();
+    const started = performance.now();
+    for (let batch = 0; batch < 10; batch += 1) {
+      const results = await Promise.all(Array.from({ length: 20 }, (_, i) => session.client.callTool({ name: "search_programs", arguments: { search: `fixture-${batch}-${i}`, page_size: 20 } })));
+      assert.ok(results.every((result) => !result.isError));
+    }
+    const peakHeapDelta = process.memoryUsage().heapUsed - heap;
+    const elapsed = performance.now() - started;
+    global.gc?.();
+    assert.equal(session.upstream.diagnostics().in_flight_requests, 0);
+    assert.equal(session.upstream.diagnostics().request_concurrency.active, 0);
+    concurrency.push({ calls: 200, requests: counts.requests, peak_active: counts.peak, duration_ms: round(elapsed), heap_delta_before_gc: peakHeapDelta, retained_heap_delta: process.memoryUsage().heapUsed - heap });
+  }
+  const discovery = [];
+  for (const session of pair) {
+    const listed = await session.client.listTools();
+    discovery.push({ tools: listed.tools.length, bytes: Buffer.byteLength(JSON.stringify(listed)) });
+  }
+  process.stdout.write(JSON.stringify({ baseline_commit: baselineCommit, fixture: true, simulated_latency_ms: 5,
+    comparison: "Same inputs; caches disabled for common workflows. Array entries are baseline, candidate.",
+    workflows: report, repeated_reads: repeated, concurrency, discovery }, null, 2) + "\n");
+} finally {
+  for (const session of sessions) { await session.client.close(); await session.server.close(); }
+  api.close();
+  // Only remove the exact temporary directory created above, after unlinking its dependency junction.
+  if (path.dirname(temporary) !== path.resolve(os.tmpdir()) || !path.basename(temporary).startsWith("bbradar-compare-")) throw new Error("Unexpected temporary directory");
+  if (fs.existsSync(path.join(temporary, "node_modules"))) fs.unlinkSync(path.join(temporary, "node_modules"));
+  fs.rmSync(temporary, { recursive: true, force: true });
+}

package/benchmark/pro-benchmark.mjs

@@ -0,0 +1,84 @@
+import http from "node:http";
+import { performance } from "node:perf_hooks";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { BBRadarClient } from "../dist/bbradarClient.js";
+import { createBbradarServer } from "../dist/server.js";
+
+const counters = { requests: 0, bytes: 0, active: 0, peak: 0 };
+const historyRows = Array.from({ length: 10 }, (_, i) => ({ id: `c${i}`, program: { id: "HackerOne:bench" }, category: "scope", observed_at: "2026-09-24T00:00:00Z" }));
+const responses = {
+  "/pro/history/changes": { changes: historyRows, coverage: { capture_enabled: true }, meta: { has_more: false, next_cursor: null } },
+  "/pro/activity/programs/HackerOne:bench": { program_id: "HackerOne:bench", activity_summary: { additions: 0, last_observed_at: null } },
+  "/pro/analytics/programs/activity": { programs: historyRows.map((row) => ({ id: row.program.id, activity_days: 1 })), meta: { generation: 3, provisional: false, unsupported_metrics: ["repository_changes"] } }
+};
+const api = http.createServer(async (req, res) => {
+  const path = new URL(req.url, "http://fixture").pathname.replace(/^\/api\/v1/, "");
+  counters.requests += 1;
+  counters.active += 1;
+  counters.peak = Math.max(counters.peak, counters.active);
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  const payload = path === "/pro/capabilities"
+    ? { contract_version: "2026-09-24", endpoints: Object.fromEntries(["history_changes", "history_change_detail", "program_activity", "analytics_program_activity"].map((key) => [key, { enabled: true, history_capture_enabled: true }])) }
+    : path.startsWith("/pro/history/changes/")
+      ? { change: historyRows[0], items: [{ before: null, after: { count: 0 } }], meta: { has_more: false } }
+      : responses[path] ?? { detail: "missing" };
+  const body = JSON.stringify(payload);
+  counters.bytes += Buffer.byteLength(body);
+  res.setHeader("content-type", "application/json");
+  res.setHeader("cache-control", "private, no-store");
+  res.end(body);
+  counters.active -= 1;
+});
+
+await new Promise((resolve) => api.listen(0, "127.0.0.1", resolve));
+const base = `http://127.0.0.1:${api.address().port}/api/v1`;
+const options = { apiKey: "benchmark", apiBaseUrl: base, webBaseUrl: "https://bbradar.io", cacheTtlMs: 30_000, negativeCacheTtlMs: 15_000, cacheMaxEntries: 50, defaultRateLimitPerMinute: 60, exportRateLimitPerMinute: 15, maxConcurrentRequests: 6, compactToolText: true, toolProfile: "core", requestTimeoutMs: 5_000, validateOnStartup: false };
+const upstream = new BBRadarClient(options);
+await upstream.negotiateCapabilities();
+const server = createBbradarServer(upstream, options);
+const client = new Client({ name: "pro-benchmark", version: "1" });
+const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+
+function reset() { counters.requests = 0; counters.bytes = 0; counters.peak = 0; }
+function percentile(values, p) { const sorted = [...values].sort((a, b) => a - b); return Math.round(sorted[Math.min(sorted.length - 1, Math.ceil(p * sorted.length) - 1)] * 100) / 100; }
+async function measure(name, args) {
+  reset();
+  const timings = [];
+  let result;
+  const heapBefore = process.memoryUsage().heapUsed;
+  for (let i = 0; i < 20; i += 1) {
+    const start = performance.now();
+    result = await client.callTool({ name, arguments: args });
+    timings.push(performance.now() - start);
+    if (result.isError) throw new Error(`${name} failed`);
+  }
+  return { calls: 20, upstream_requests: counters.requests, upstream_bytes: counters.bytes, model_text_bytes: Buffer.byteLength(result.content[0].text), structured_bytes: Buffer.byteLength(JSON.stringify(result.structuredContent)), p50_ms: percentile(timings, .5), p95_ms: percentile(timings, .95), heap_delta_bytes: process.memoryUsage().heapUsed - heapBefore };
+}
+
+async function measureDirect(path) {
+  reset();
+  const timings = [];
+  for (let i = 0; i < 20; i += 1) {
+    const start = performance.now();
+    const response = await fetch(base + path, { headers: { authorization: "Bearer benchmark" } });
+    await response.arrayBuffer();
+    timings.push(performance.now() - start);
+  }
+  return { calls: 20, upstream_requests: counters.requests, upstream_bytes: counters.bytes, p50_ms: percentile(timings, .5), p95_ms: percentile(timings, .95) };
+}
+
+try {
+  const directHistory = await measureDirect("/pro/history/changes?limit=10");
+  const history = await measure("get_history_changes", { limit: 10 });
+  const detail = await measure("get_history_change_detail", { change_id: "c0", limit: 1 });
+  const activity = await measure("get_program_activity", { program_id: "HackerOne:bench" });
+  const analytics = await measure("get_analytics_program_activity", { limit: 10 });
+  reset();
+  const heapBefore = process.memoryUsage().heapUsed;
+  const parallel = await Promise.all(Array.from({ length: 10 }, (_, i) => client.callTool({ name: "get_history_changes", arguments: { search: `bench${i}`, limit: 1 } })));
+  const concurrency = { calls: parallel.length, upstream_requests: counters.requests, peak_upstream_requests: counters.peak, heap_delta_bytes: process.memoryUsage().heapUsed - heapBefore };
+  if ([history, detail, activity, analytics].some((entry) => entry.upstream_requests !== 20) || concurrency.peak_upstream_requests > 2 || concurrency.upstream_requests !== 10) throw new Error("Pro request-count or shared-concurrency regression");
+  process.stdout.write(JSON.stringify({ fixture: true, simulated_upstream_delay_ms: 5, direct_history: directHistory, estimated_mcp_overhead_p50_ms: Math.round((history.p50_ms - directHistory.p50_ms) * 100) / 100, history_lazy_detail: { eager_baseline_requests: 11, feed_only_requests: 1, requested_detail_requests: 2 }, tools: { history, detail, activity, analytics }, concurrency }, null, 2) + "\n");
+} finally { await client.close(); await server.close(); api.close(); }

package/dist/bbradarClient.d.ts

@@ -9,8 +9,9 @@ export type ApiRequestOptions = {
     coalesce?: boolean;
     staleWhileRevalidateMs?: number;
     timeoutMs?: number;
+    signal?: AbortSignal;
 };
-export type ApiReadControls = Pick<ApiRequestOptions, "cache" | "coalesce" | "timeoutMs">;
+export type ApiReadControls = Pick<ApiRequestOptions, "cache" | "coalesce" | "timeoutMs" | "signal">;
 export type ApiResult<T> = {
     data: T;
     requestId: string;
@@ -21,6 +22,7 @@ export type ApiResult<T> = {
     fetchedAt: string;
     cacheExpiresAt?: string | undefined;
     stale?: boolean | undefined;
+    noStore?: boolean | undefined;
 };
 type CapabilityNegotiationState = {
     status: "not_started" | "negotiated" | "legacy" | "failed";
@@ -37,6 +39,7 @@ export declare class BBRadarApiError extends Error {
     readonly cached: boolean;
     readonly coalesced: boolean;
     readonly cacheExpiresAt: string | undefined;
+    readonly cacheAllowed: boolean;
     constructor(params: {
         message: string;
         requestId: string;
@@ -47,6 +50,7 @@ export declare class BBRadarApiError extends Error {
         cached?: boolean | undefined;
         coalesced?: boolean | undefined;
         cacheExpiresAt?: string | undefined;
+        cacheAllowed?: boolean | undefined;
         cause?: unknown;
     });
 }
@@ -55,6 +59,8 @@ export declare class BBRadarClient {
     private readonly cache;
     private readonly negativeCache;
     private readonly inFlight;
+    private readonly sharedRequests;
+    private readonly requestContext;
     private readonly endpointMetrics;
     private readonly requestQueue;
     private readonly endpointRequestQueues;
@@ -67,6 +73,7 @@ export declare class BBRadarClient {
     private capabilityNegotiation;
     private capabilityState;
     constructor(config: ServerConfig);
+    withRequestContext<T>(signal: AbortSignal, callback: () => T | Promise<T>, snapshotStart?: boolean): Promise<T>;
     diagnostics(): {
         response_cache: {
             entries: number;
@@ -192,8 +199,16 @@ export declare class BBRadarClient {
     getRepositoryChanges(query: Record<string, QueryValue>, controls?: ApiReadControls): Promise<ApiResult<unknown>>;
     searchTargets(query: Record<string, QueryValue>, controls?: ApiReadControls): Promise<ApiResult<unknown>>;
     getOpportunities(level: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getHistoryChanges(query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getHistoryChangeDetail(changeId: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getProgramHistory(programId: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getProgramActivity(programId: string): Promise<ApiResult<unknown>>;
+    getAnalyticsPlatformSeries(platform: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getAnalyticsProgramActivity(query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
+    getAnalyticsProgramDetail(programId: string, query: Record<string, QueryValue>): Promise<ApiResult<unknown>>;
     exportTargets(body: Record<string, unknown>): Promise<ApiResult<unknown>>;
     request<T = unknown>(options: ApiRequestOptions): Promise<ApiResult<T>>;
+    private requestWithSignal;
     private fetchFromApi;
     private refreshInBackground;
     private withRequestSlot;