The core new abstraction

@pcarleton: added tests covering both authentication modes here

🟡 Nit: SSE _startOrAuth() has no circuit breaker for repeated 401s — if onUnauthorized always resolves but the server keeps returning 401, the retry loop has no upper bound, unlike _startOrAuthSse(options, isAuthRetry) in StreamableHTTP and _send(message, isAuthRetry) in both transports which all limit retries. This is an acknowledged trade-off (commit 56ffc7b notes "no circuit breaker on the SSE connect path") to avoid the closure capture regression, but a counter-based approach could provide both safety and correctness. Low priority since SSE transport is deprecated.

What the bug is

The SSE _startOrAuth() method has no isAuthRetry parameter or equivalent circuit breaker. When the onerror handler fires on 401, onUnauthorized is called, and on success, this._startOrAuth().then(resolve, reject) recursively creates a new EventSource. If the new EventSource also gets 401, the cycle repeats with no upper bound.

All three other 401 retry paths in the codebase have circuit breakers:

• _startOrAuthSse(options, isAuthRetry = false) in streamableHttp.ts (line 199) passes true on recursive call (line 236)
• _send(message, isAuthRetry) in sse.ts passes true on recursive call
• _send(message, options, isAuthRetry) in streamableHttp.ts passes true on recursive call

Why the parameter was deliberately removed

Commit 56ffc7b explicitly removed isAuthRetry from _startOrAuth(). The commit message explains the architectural reason: the SSE EventSource model is fundamentally different from one-shot fetch calls. The onerror closure lives for the lifetime of the EventSource. Passing _startOrAuth(true) on retry bakes isAuthRetry=true into the new EventSource's closure permanently. If that EventSource later auto-reconnects (e.g., network drop on a long-lived stream hours later) and gets 401, onUnauthorized would be skipped and the transport could never recover from token expiration.

The commit acknowledges this trade-off explicitly: "no circuit breaker on the SSE connect path — if onUnauthorized succeeds but server keeps 401ing, it loops (same as pre-PR)."

The infinite loop scenario

Concrete scenario: an AuthProvider whose onUnauthorized successfully refreshes a token (resolves), but the server permanently rejects the new token (e.g., token was revoked server-side, scope insufficient, client banned):

1. _startOrAuth() creates EventSource → fetch returns 401 → _last401Response set
2. onerror fires → onUnauthorized called → resolves (token refreshed)
3. this._startOrAuth().then(resolve, reject) → new EventSource → fetch returns 401 → _last401Response set
4. New EventSource's onerror fires → onUnauthorized called → resolves again
5. Repeat indefinitely — no counter, no flag, no limit

The test at line 1628 validates multi-retry (2 calls to onUnauthorized, 3rd attempt succeeds), confirming the behavior is intentional. The test terminates because the mock server stops returning 401 on the 3rd attempt — but there's nothing in the code that would stop it if the server never stops.

Why practical impact is low

1. SSE transport is deprecated in favor of StreamableHTTP.
2. Built-in handleOAuthUnauthorized calls auth() which will throw UnauthorizedError if the result is not AUTHORIZED (e.g., redirect needed, discovery failure), naturally terminating the loop in most OAuth scenarios.
3. Custom AuthProvider.onUnauthorized implementations that always resolve regardless of server state are unusual — most will eventually detect the persistent failure and throw.
4. The pre-PR _authThenStart() had the same behavior (no circuit breaker), so this is not a regression from the pre-PR baseline.

Possible fix that avoids the closure capture problem

A counter-based approach would provide both safety and correctness without the closure capture issue:

private _connectRetryCount = 0;
// In onerror:
if (++this._connectRetryCount > MAX_CONNECT_RETRIES) { reject(new UnauthorizedError()); return; }
// Reset on successful connection (in the endpoint event handler):
this._connectRetryCount = 0;

This avoids baking state into the EventSource closure while still providing an upper bound.

🟡 Nit: 401 response bodies are never drained when onUnauthorized() throws in the three async retry paths (_startOrAuthSse line 229, _send streamableHttp line 522, _send SSE line 278), and are never drained at all in the SSE connect onerror handler (lines 148-170). In Node.js (undici), unconsumed response bodies prevent TCP socket recycling until GC. Fix: wrap onUnauthorized() + drain in try/finally in the async paths; add response.text?.().catch(() => {}) in the SSE onerror paths.

What the bug is

There are two related issues where 401 response bodies are left unconsumed:

Issue 1 — onUnauthorized() failure path: In all three async 401 retry paths, the response.text() drain call is positioned after await onUnauthorized(). If onUnauthorized() throws (e.g., network error during token refresh), execution jumps directly to the catch block, skipping the drain:

// streamableHttp.ts _startOrAuthSse (line 229-234), same in _send (522-527) and sse.ts _send (278-283)
await this._authProvider.onUnauthorized({ response, ... });  // throws here
await response.text?.().catch(() => {});  // skipped
return this._startOrAuthSse(options, true);

The catch blocks do not drain the response either — they just call onerror and rethrow.

Issue 2 — SSE connect onerror handler: In the SSE onerror handler (lines 148-170), the 401 response stored in _last401Response is never consumed in any path. The response object is passed to onUnauthorized() which only reads headers via extractWWWAuthenticateParams(). After onUnauthorized succeeds, the code calls _startOrAuth() without draining. After it fails, the error is reported without draining. When there is no onUnauthorized, UnauthorizedError is thrown without draining. In contrast, all three _send() paths consistently drain the body.

Step-by-step proof for Issue 1

1. Client calls send(message) — server responds with 401.
2. Transport enters the onUnauthorized branch at line 521 (streamableHttp _send).
3. onUnauthorized() is awaited at line 522 — it throws (e.g., DNS failure reaching auth server).
4. The error propagates to the catch block. The response.text() call at line 527 is never reached.
5. The 401 Response object goes out of scope with its body stream unconsumed.
6. In Node.js (undici), the underlying TCP socket cannot be returned to the keep-alive pool until the Response is garbage collected.

Step-by-step proof for Issue 2

1. transport.start() calls _startOrAuth().
2. The EventSource's fetch wrapper captures the 401 response at line 135: this._last401Response = response.
3. The onerror handler fires. At line 151, the response reference is moved to a local variable.
4. onUnauthorized({ response, ... }) is called. handleOAuthUnauthorized only calls extractWWWAuthenticateParams(ctx.response) which reads headers — the body is never consumed.
5. On success, this._startOrAuth().then(resolve, reject) runs — the original 401 response body remains unconsumed.
6. On failure, reject(error) is called — the response body remains unconsumed.

Impact

Practical impact is low: (1) 401 response bodies are typically small or empty, (2) GC will reclaim the socket quickly, (3) these are uncommon error paths (onUnauthorized throwing is itself an edge case), and (4) the SSE transport is deprecated. Socket exhaustion would require sustained rapid onUnauthorized failures, which is unusual. However, the fix is trivial and matches the drain pattern already used everywhere else in this code.

How to fix

For Issue 1, wrap onUnauthorized() + drain in try/finally in all three async paths:

try {
    await this._authProvider.onUnauthorized({ response, ... });
} finally {
    await response.text?.().catch(() => {});
}
return this._send(message, options, true);

For Issue 2, add a drain call in the SSE onerror handler after capturing the response:

const response = this._last401Response;
this._last401Response = undefined;
response.text?.().catch(() => {});  // fire-and-forget drain