feat(toolkit-core): Let a request scope bypass cached reads (#1720)

This adds a request-scoped fresh-read bypass to the shared API transport
in `@sentry/toolkit-core/api-transport`. It is task **5.3** of #1669
(`unify-sentry-api-layer`) and builds on the shared transport from
#1719.

### What's shared

`createApiTransport` accepts a new optional `fresh?(): boolean` hook.
While the hook returns true:

- GETs skip the cache lookup and go to the network.
- The response is still stored, so it replaces the cached entry and
later reads see the new data.

A host backs the hook with request-scoped state, for example
`AsyncLocalStorage` around a single MCP tool call that asked for `fresh:
true`. That keeps the bypass to one call rather than the whole process.
This is the transport side of the MCP's `fresh` input planned in 6.3.

### Behavior changes

None for current callers. The hook is optional, and no host sets it yet.
The CLI's `--fresh` flag keeps its existing process-wide bypass in
`cli/src/lib/response-cache.ts`, with reads skipped and writes kept as
before. This PR leaves that unchanged.

### Relation to #1669

- Done: 5.0 shared retry policy (#1673, #1710), and 5.1 + 5.2 shared
transport with the CLI switch (#1719).
- This PR: 5.3.
- Next, stacked on this branch and opened once it merges: 6.1. That adds
`fetch` to `McpServerOptions` and routes all `SentryApiService` and
`@sentry/api` requests through it. `SentryApiService` drops its own
retry loop, so retries happen in the shared transport only.

### Verification

- New transport test `skips the cache in a fresh scope and replaces the
entry`. It stores v1, then reads in a fresh scope and gets v2 from the
network. Once the fresh scope ends, the next read is a cache hit for v2.
- `toolkit-core`: 21 files and 270 tests pass.
- CLI request, cache and API tests (`test/lib/sentry-client*`,
`test/lib/response-cache*`, `test/lib/api`): 49 files and 1,049 tests
pass.
- `tsc --noEmit` passes for `toolkit-core` and `cli`.
- `oxlint`, `oxfmt --check` and `ast-grep scan` are clean on the changed
files.

<!-- junior-request-attribution:start -->
via **BYK**.
<!-- junior-request-attribution:end -->

<!-- junior-session-footer:start -->
<!-- junior-conversation-id:agent%3Aa6eddc0161cff61914454da9f74fcdf1 -->

--

[View Junior Session in
Sentry](https://sentry.sentry.io/explore/conversations/agent%3Aa6eddc0161cff61914454da9f74fcdf1/?project=4510944073809921)

<!-- junior-session-footer:end -->

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: BYK <burak.kaya@sentry.io>

Author: sentry-junior[bot]

packages/toolkit-core/README.md

@@ -26,7 +26,9 @@ With `validateRedirects`, it follows redirects by hand, sends the credential
 only to origins the host trusts, and records the final origin for
 `getValidatedResponseSource`. With a cache, a GET is looked up first (a stale
 entry is revalidated with its `ETag`), a successful GET is stored, and a
-successful write invalidates what it made stale.
+successful write invalidates what it made stale. While the host's `fresh`
+hook returns true, such as during a tool call that asked for fresh data, GETs
+skip the lookup and their responses replace the cached entry.
 
 The host passes in a `CredentialProvider` (the current credential, an optional
 refresh ahead of expiry, and the 401 refresh), header rules that may reject a

packages/toolkit-core/src/api-transport.test.ts

@@ -536,6 +536,37 @@ describe("cache", () => {
     expect(sent).toHaveLength(1);
   });
 
+  it("skips the cache in a fresh scope and replaces the entry", async () => {
+    const cache = memoryCache();
+    const { fetch, sent } = scriptedFetch([
+      Response.json({ v: 1 }),
+      Response.json({ v: 2 }),
+    ]);
+    let fresh = false;
+    const api = transport(fetch, { cache, fresh: () => fresh });
+    const stored = async (v: number) =>
+      await vi.waitFor(async () => {
+        const lookup = await cache.lookup({
+          url: ISSUES_URL,
+          requestHeaders: { authorization: "Bearer token-a" },
+          identity: "id-a",
+        });
+        expect(
+          lookup?.kind === "hit" ? await lookup.response.json() : undefined,
+        ).toEqual({ v });
+      });
+
+    await api.request(ISSUES_URL);
+    await stored(1);
+    fresh = true;
+    expect(await (await api.request(ISSUES_URL)).json()).toEqual({ v: 2 });
+    await stored(2);
+    fresh = false;
+
+    expect(await (await api.request(ISSUES_URL)).json()).toEqual({ v: 2 });
+    expect(sent).toHaveLength(2);
+  });
+
   it("revalidates a stale entry with its ETag", async () => {
     const response = await transport(
       scriptedFetch([new Response(null, { status: 304 })]).fetch,

packages/toolkit-core/src/api-transport.ts

@@ -106,6 +106,12 @@ export type ApiTransportOptions<C extends TransportCredential> = {
     ): Promise<Error | undefined>;
   };
   cache?: TransportCache;
+  /**
+   * Whether the current scope skips cache reads, such as a tool call with
+   * `fresh: true`. Hosts back it with request-scoped state like
+   * `AsyncLocalStorage`. The response is still stored, replacing the entry.
+   */
+  fresh?(): boolean;
   logger?: TransportLogger;
   /** Wrap each request, including cache lookups, in a host span. */
   span?(
@@ -663,7 +669,10 @@ export function createApiTransport<C extends TransportCredential>(
       // A cached response has no validated origin, so discovery always
       // goes to the network.
       const lookup =
-        cache && method === "GET" && !options.validateRedirects
+        cache &&
+        method === "GET" &&
+        !options.validateRedirects &&
+        !config.fresh?.()
           ? await cache.lookup({
               url,
               // Before a refresh picks the token, so validate nothing yet.