@adcp/sdk 16.0.0-beta.2 → 16.0.0-beta.3

package/dist/lib/protocols/index.d.mts

@@ -11,6 +11,7 @@ export { withMCPConnectionScope };
 export type { MCPCallOptions, MCPConnectionResult } from './mcp.mjs';
 export { callA2ATool, createA2AClientFromCardUrl } from './a2a.mjs';
 export { DEFAULT_REQUEST_TIMEOUT_MS } from './abort.mjs';
+export { DEFAULT_MAX_RESPONSE_BYTES, SSE_CUMULATIVE_BUDGET_MULTIPLIER } from './responseSizeLimit.mjs';
 export { callMCPToolWithTasks, getMCPTaskStatus, getMCPTaskResult, listMCPTasks, cancelMCPTask, mapMCPTaskStatus, serverSupportsTasks, } from './mcp-tasks.mjs';
 import type { AgentConfig, DebugLogEntry } from '../types/index.mjs';
 import type { PushNotificationConfig } from '../types/tools.generated.mjs';
@@ -36,36 +37,71 @@ export declare function bundleSupportsAdcpVersionField(bundleKey: string): boole
 export interface TransportOptions {
     /**
      * Maximum response body size (in octets) the SDK will read before aborting
-     * with `ResponseTooLargeError`. When unset, the SDK does not impose a cap —
-     * matches the underlying MCP / A2A transport defaults.
+     * with `ResponseTooLargeError`.
      *
-     * Set this when crawling **untrusted** agents (registries, federated
-     * discovery layers, monitoring tools) to prevent a hostile vendor from
-     * buffering a large reply before any application-layer schema validation
-     * runs. Counted across response chunks; pre-cancels when `Content-Length`
-     * exceeds the cap. Applies to A2A agent-card discovery
-     * (`/.well-known/agent.json`) on the same call as well.
+     * **Defaults to 4 MiB** (`DEFAULT_MAX_RESPONSE_BYTES`). Agent responses are
+     * untrusted input, so the cap is on by default on every MCP and A2A call
+     * path — tool calls, endpoint discovery, `tools/list`, and A2A agent-card
+     * lookup (`/.well-known/agent.json`). Counted across response chunks as
+     * they arrive; pre-cancels when `Content-Length` already exceeds the cap.
      *
-     * Per-call override (`TaskOptions.transport.maxResponseBytes`) beats the
-     * value set on the client constructor (`SingleAgentClientConfig.transport`).
+     * Raise it for an agent that legitimately publishes a large catalog; lower
+     * it when crawling **untrusted** agents (registries, federated discovery
+     * layers, monitoring tools). Set it to exactly `0` to opt out of
+     * enforcement entirely — an explicit opt-out, never the default. `Infinity`
+     * and negative values are *not* opt-outs: they fall back to the 4 MiB
+     * default, because they almost always arrive from a misparsed env var or a
+     * budget subtraction rather than an intention. Use `0`.
+     *
+     * Per-call `transport` **replaces** the client constructor's `transport`
+     * object rather than merging field by field
+     * (`TaskOptions.transport` ?? `SingleAgentClientConfig.transport`), so a
+     * per-call object that omits `maxResponseBytes` gets the default back, not
+     * the constructor's value. Repeat the field when you override the object.
+     *
+     * Cached MCP connections are keyed on the cap, so varying it per call opens
+     * a separate connection (and MCP session) per distinct value against the
+     * same agent. That is deliberate — a connection established under one
+     * policy must not serve a call that configured another — but it means
+     * raising the cap for one tool is not free. Prefer a single client-level
+     * value where you can, or pin the session explicitly with
+     * `withMCPConnectionScope` when continuity matters.
      *
      * @remarks
-     * **Safe to set on all calls.** SSE responses (`text/event-stream`) are
-     * passed through unchanged — a single tool call legitimately emits N status
-     * frames + a final result, bounded by protocol-level framing rather than
-     * cumulative byte counts. The cap applies to one-shot JSON responses
-     * (`get_adcp_capabilities`, agent-card lookup, tool result payloads on
-     * non-streaming transports) where the body is bounded by definition.
+     * **SSE is covered too.** `text/event-stream` responses used to be exempt,
+     * which let any peer opt itself out of the cap by changing one response
+     * header. They now carry two bounds: no single event frame may exceed
+     * `maxResponseBytes` (the memory bound — an SSE consumer buffers one frame
+     * at a time), and the cumulative event-stream octets read during one call
+     * may not exceed `maxResponseBytes * 2`
+     * (`SSE_CUMULATIVE_BUDGET_MULTIPLIER`, the liveness bound that stops an
+     * endless drip of individually legal frames). Both failures raise the same
+     * `ResponseTooLargeError`; nothing is silently truncated.
+     *
+     * A long-lived `GET` event-stream — MCP's standalone notification listener,
+     * the legacy SSE transport — outlives the call that opened it, so it meters
+     * its cumulative allowance per *connection* instead of per call. That makes
+     * the cumulative number a memory bound there, not a liveness bound: a peer
+     * that keeps tripping it gets a reconnect cycle at a bounded cost per
+     * cycle. Cached connections are keyed on the cap in effect, so a listener
+     * is only ever reused by calls that configured the same policy as the call
+     * that opened it.
      *
      * @remarks
-     * **Hostile-peer note:** A peer can opt itself out of this cap by responding
-     * with `Content-Type: text/event-stream`. SSE is bypassed because cumulative
-     * event-frame bytes are unbounded by spec — MCP and A2A both stream tool
-     * responses this way. The MCP/A2A SDKs consume SSE incrementally and frame
-     * termination bounds memory in practice, so this is not a memory-bomb risk
-     * for well-formed transports. Adopters relying on `maxResponseBytes` as a
-     * hostile-server defense should treat it as best-effort for non-SSE
-     * responses only.
+     * **Compression and streaming failures.** The byte counter runs downstream
+     * of the runtime's content-decoder, so it measures decompressed octets: a
+     * small gzip blob that inflates to gigabytes still trips the cap after
+     * `maxResponseBytes` of output. The `Content-Length` pre-check, by
+     * contrast, sees the compressed length and is therefore only a fast path,
+     * not the guarantee.
+     *
+     * On a streaming transport the cap errors the response body. Some
+     * transports classify that as a stream disconnect and retry rather than
+     * propagating it, so the call would otherwise run out its deadline: the SDK
+     * records the violation and, if the call then fails, raises
+     * `ResponseTooLargeError` with the transport's own error as `cause` instead
+     * of the timeout. A buyer never gets a timeout for what is really an
+     * over-cap response.
      *
      * @remarks
      * Future hardening knobs (DNS-rebind defense, scheme allow-list, request

package/dist/lib/protocols/index.d.ts

@@ -11,6 +11,7 @@ export { withMCPConnectionScope };
 export type { MCPCallOptions, MCPConnectionResult } from './mcp';
 export { callA2ATool, createA2AClientFromCardUrl } from './a2a';
 export { DEFAULT_REQUEST_TIMEOUT_MS } from './abort';
+export { DEFAULT_MAX_RESPONSE_BYTES, SSE_CUMULATIVE_BUDGET_MULTIPLIER } from './responseSizeLimit';
 export { callMCPToolWithTasks, getMCPTaskStatus, getMCPTaskResult, listMCPTasks, cancelMCPTask, mapMCPTaskStatus, serverSupportsTasks, } from './mcp-tasks';
 import type { AgentConfig, DebugLogEntry } from '../types';
 import type { PushNotificationConfig } from '../types/tools.generated';
@@ -36,36 +37,71 @@ export declare function bundleSupportsAdcpVersionField(bundleKey: string): boole
 export interface TransportOptions {
     /**
      * Maximum response body size (in octets) the SDK will read before aborting
-     * with `ResponseTooLargeError`. When unset, the SDK does not impose a cap —
-     * matches the underlying MCP / A2A transport defaults.
+     * with `ResponseTooLargeError`.
      *
-     * Set this when crawling **untrusted** agents (registries, federated
-     * discovery layers, monitoring tools) to prevent a hostile vendor from
-     * buffering a large reply before any application-layer schema validation
-     * runs. Counted across response chunks; pre-cancels when `Content-Length`
-     * exceeds the cap. Applies to A2A agent-card discovery
-     * (`/.well-known/agent.json`) on the same call as well.
+     * **Defaults to 4 MiB** (`DEFAULT_MAX_RESPONSE_BYTES`). Agent responses are
+     * untrusted input, so the cap is on by default on every MCP and A2A call
+     * path — tool calls, endpoint discovery, `tools/list`, and A2A agent-card
+     * lookup (`/.well-known/agent.json`). Counted across response chunks as
+     * they arrive; pre-cancels when `Content-Length` already exceeds the cap.
      *
-     * Per-call override (`TaskOptions.transport.maxResponseBytes`) beats the
-     * value set on the client constructor (`SingleAgentClientConfig.transport`).
+     * Raise it for an agent that legitimately publishes a large catalog; lower
+     * it when crawling **untrusted** agents (registries, federated discovery
+     * layers, monitoring tools). Set it to exactly `0` to opt out of
+     * enforcement entirely — an explicit opt-out, never the default. `Infinity`
+     * and negative values are *not* opt-outs: they fall back to the 4 MiB
+     * default, because they almost always arrive from a misparsed env var or a
+     * budget subtraction rather than an intention. Use `0`.
+     *
+     * Per-call `transport` **replaces** the client constructor's `transport`
+     * object rather than merging field by field
+     * (`TaskOptions.transport` ?? `SingleAgentClientConfig.transport`), so a
+     * per-call object that omits `maxResponseBytes` gets the default back, not
+     * the constructor's value. Repeat the field when you override the object.
+     *
+     * Cached MCP connections are keyed on the cap, so varying it per call opens
+     * a separate connection (and MCP session) per distinct value against the
+     * same agent. That is deliberate — a connection established under one
+     * policy must not serve a call that configured another — but it means
+     * raising the cap for one tool is not free. Prefer a single client-level
+     * value where you can, or pin the session explicitly with
+     * `withMCPConnectionScope` when continuity matters.
      *
      * @remarks
-     * **Safe to set on all calls.** SSE responses (`text/event-stream`) are
-     * passed through unchanged — a single tool call legitimately emits N status
-     * frames + a final result, bounded by protocol-level framing rather than
-     * cumulative byte counts. The cap applies to one-shot JSON responses
-     * (`get_adcp_capabilities`, agent-card lookup, tool result payloads on
-     * non-streaming transports) where the body is bounded by definition.
+     * **SSE is covered too.** `text/event-stream` responses used to be exempt,
+     * which let any peer opt itself out of the cap by changing one response
+     * header. They now carry two bounds: no single event frame may exceed
+     * `maxResponseBytes` (the memory bound — an SSE consumer buffers one frame
+     * at a time), and the cumulative event-stream octets read during one call
+     * may not exceed `maxResponseBytes * 2`
+     * (`SSE_CUMULATIVE_BUDGET_MULTIPLIER`, the liveness bound that stops an
+     * endless drip of individually legal frames). Both failures raise the same
+     * `ResponseTooLargeError`; nothing is silently truncated.
+     *
+     * A long-lived `GET` event-stream — MCP's standalone notification listener,
+     * the legacy SSE transport — outlives the call that opened it, so it meters
+     * its cumulative allowance per *connection* instead of per call. That makes
+     * the cumulative number a memory bound there, not a liveness bound: a peer
+     * that keeps tripping it gets a reconnect cycle at a bounded cost per
+     * cycle. Cached connections are keyed on the cap in effect, so a listener
+     * is only ever reused by calls that configured the same policy as the call
+     * that opened it.
      *
      * @remarks
-     * **Hostile-peer note:** A peer can opt itself out of this cap by responding
-     * with `Content-Type: text/event-stream`. SSE is bypassed because cumulative
-     * event-frame bytes are unbounded by spec — MCP and A2A both stream tool
-     * responses this way. The MCP/A2A SDKs consume SSE incrementally and frame
-     * termination bounds memory in practice, so this is not a memory-bomb risk
-     * for well-formed transports. Adopters relying on `maxResponseBytes` as a
-     * hostile-server defense should treat it as best-effort for non-SSE
-     * responses only.
+     * **Compression and streaming failures.** The byte counter runs downstream
+     * of the runtime's content-decoder, so it measures decompressed octets: a
+     * small gzip blob that inflates to gigabytes still trips the cap after
+     * `maxResponseBytes` of output. The `Content-Length` pre-check, by
+     * contrast, sees the compressed length and is therefore only a fast path,
+     * not the guarantee.
+     *
+     * On a streaming transport the cap errors the response body. Some
+     * transports classify that as a stream disconnect and retry rather than
+     * propagating it, so the call would otherwise run out its deadline: the SDK
+     * records the violation and, if the call then fails, raises
+     * `ResponseTooLargeError` with the transport's own error as `cause` instead
+     * of the timeout. A buyer never gets a timeout for what is really an
+     * over-cap response.
      *
      * @remarks
      * Future hardening knobs (DNS-rebind defense, scheme allow-list, request

package/dist/lib/protocols/index.js

@@ -19,9 +19,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var protocols_exports = {};
 __export(protocols_exports, {
   BODY_SNIPPET_TIMEOUT_MS: () => import_transportDiagnostics2.BODY_SNIPPET_TIMEOUT_MS,
+  DEFAULT_MAX_RESPONSE_BYTES: () => import_responseSizeLimit.DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_REQUEST_TIMEOUT_MS: () => import_abort.DEFAULT_REQUEST_TIMEOUT_MS,
   OBSERVER_FLUSH_TIMEOUT_MS: () => import_transportDiagnostics2.OBSERVER_FLUSH_TIMEOUT_MS,
   ProtocolClient: () => ProtocolClient,
+  SSE_CUMULATIVE_BUDGET_MULTIPLIER: () => import_responseSizeLimit.SSE_CUMULATIVE_BUDGET_MULTIPLIER,
   UnauthorizedError: () => import_mcp.UnauthorizedError,
   applyVersionEnvelope: () => applyVersionEnvelope,
   bundleSupportsAdcpVersionField: () => bundleSupportsAdcpVersionField,
@@ -59,6 +61,7 @@ var import_a2a = require('./a2a.js');
 var import_node_crypto = require("node:crypto");
 var import_a2a2 = require('./a2a.js');
 var import_abort = require('./abort.js');
+var import_responseSizeLimit = require('./responseSizeLimit.js');
 var import_mcp_tasks = require('./mcp-tasks.js');
 var import_mcp_tasks2 = require('./mcp-tasks.js');
 var import_mcp3 = require('./mcp.js');
@@ -76,7 +79,7 @@ var import_version = require('../version.js');
 var import_errors2 = require('../errors/index.js');
 var import_schema_loader = require('../validation/schema-loader.js');
 var import_client = require('../signing/client.js');
-var import_responseSizeLimit = require('./responseSizeLimit.js');
+var import_responseSizeLimit2 = require('./responseSizeLimit.js');
 var import_prepared_call_context = require('./prepared-call-context.js');
 var import_adcp_version_config = require('../utils/adcp-version-config.js');
 var import_transportDiagnostics = require('./transportDiagnostics.js');
@@ -259,7 +262,7 @@ class ProtocolClient {
       wireAdcpVersion,
       versionEnvelope: versionEnvelopeMode
     });
-    return (0, import_responseSizeLimit.withResponseSizeLimit)(
+    return (0, import_responseSizeLimit2.withResponseSizeLimit)(
       transport?.maxResponseBytes,
       () => (0, import_transportDiagnostics.withTransportDiagnostics)(
         {
@@ -523,7 +526,7 @@ const createMCPClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
   transport = normalizeTransportOptions(transport);
   const versionEnvelope = buildVersionEnvelopeForMode(versionEnvelopeMode, adcpVersion, serverVersion);
   return {
-    callTool: (toolName, args, debugLogs) => (0, import_responseSizeLimit.withResponseSizeLimit)(
+    callTool: (toolName, args, debugLogs) => (0, import_responseSizeLimit2.withResponseSizeLimit)(
       transport?.maxResponseBytes,
       () => (0, import_mcp_tasks2.callMCPToolWithTasks)(
         agentUrl,
@@ -545,7 +548,7 @@ const createA2AClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
   transport = normalizeTransportOptions(transport);
   const versionEnvelope = buildVersionEnvelopeForMode(versionEnvelopeMode, adcpVersion, serverVersion);
   return {
-    callTool: (toolName, parameters, debugLogs) => (0, import_responseSizeLimit.withResponseSizeLimit)(
+    callTool: (toolName, parameters, debugLogs) => (0, import_responseSizeLimit2.withResponseSizeLimit)(
       transport?.maxResponseBytes,
       () => (0, import_a2a3.callA2ATool)(
         agentUrl,
@@ -569,9 +572,11 @@ const createA2AClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BODY_SNIPPET_TIMEOUT_MS,
+  DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_REQUEST_TIMEOUT_MS,
   OBSERVER_FLUSH_TIMEOUT_MS,
   ProtocolClient,
+  SSE_CUMULATIVE_BUDGET_MULTIPLIER,
   UnauthorizedError,
   applyVersionEnvelope,
   bundleSupportsAdcpVersionField,

package/dist/lib/protocols/index.mjs

@@ -31,6 +31,7 @@ async function closeScopedConnections(protocol = "mcp") {
 }
 import { callA2ATool, createA2AClientFromCardUrl } from "./a2a.mjs";
 import { DEFAULT_REQUEST_TIMEOUT_MS } from "./abort.mjs";
+import { DEFAULT_MAX_RESPONSE_BYTES, SSE_CUMULATIVE_BUDGET_MULTIPLIER } from "./responseSizeLimit.mjs";
 import {
   callMCPToolWithTasks,
   getMCPTaskStatus,
@@ -548,9 +549,11 @@ const createA2AClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
 };
 export {
   BODY_SNIPPET_TIMEOUT_MS,
+  DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_REQUEST_TIMEOUT_MS,
   OBSERVER_FLUSH_TIMEOUT_MS,
   ProtocolClient,
+  SSE_CUMULATIVE_BUDGET_MULTIPLIER,
   UnauthorizedError,
   applyVersionEnvelope,
   bundleSupportsAdcpVersionField,

package/dist/lib/protocols/mcp-modern.js

@@ -102,6 +102,7 @@ function connectionCacheKey(agentUrl, headers, signingCacheKey, authProvider, fe
   if (fetchKey) parts.push(fetchKey);
   if (handleLegacy !== void 0) parts.push(`handle-legacy:${handleLegacy}`);
   if (allowPrivateIp !== void 0) parts.push(`allow-private-ip:${allowPrivateIp}`);
+  parts.push((0, import_responseSizeLimit.responseSizeCapCacheKey)());
   const scopeKey = (0, import_mcp_scope.currentMCPConnectionScopeKey)();
   if (scopeKey) parts.push(scopeKey);
   return parts.join("::");

package/dist/lib/protocols/mcp-modern.mjs

@@ -43,7 +43,7 @@ import {
 } from "./abort.mjs";
 import { wrapFetchWithCapture } from "./rawResponseCapture.mjs";
 import { wrapFetchWithSignedRequestRejection } from "./signedRequestRejection.mjs";
-import { wrapFetchWithSizeLimit } from "./responseSizeLimit.mjs";
+import { responseSizeCapCacheKey, wrapFetchWithSizeLimit } from "./responseSizeLimit.mjs";
 import { wrapFetchWithTransportDiagnostics } from "./transportDiagnostics.mjs";
 import { createAgentTransportFetch } from "../net/agent-transport-fetch.mjs";
 const modernConnections = /* @__PURE__ */ new Map();
@@ -109,6 +109,7 @@ function connectionCacheKey(agentUrl, headers, signingCacheKey, authProvider, fe
   if (fetchKey) parts.push(fetchKey);
   if (handleLegacy !== void 0) parts.push(`handle-legacy:${handleLegacy}`);
   if (allowPrivateIp !== void 0) parts.push(`allow-private-ip:${allowPrivateIp}`);
+  parts.push(responseSizeCapCacheKey());
   const scopeKey = currentMCPConnectionScopeKey();
   if (scopeKey) parts.push(scopeKey);
   return parts.join("::");

package/dist/lib/protocols/mcp.js

@@ -89,6 +89,7 @@ function connectionCacheKey(agentUrl, authToken, signingCacheKey, authHeaders, t
   if (signingCacheKey) parts.push(signingCacheKey);
   if (transportFetch) parts.push(`fetch:${getTransportFetchFnDisambiguator(transportFetch)}`);
   if (allowPrivateIp !== void 0) parts.push(`allow-private-ip:${allowPrivateIp}`);
+  parts.push((0, import_responseSizeLimit.responseSizeCapCacheKey)());
   const scopeKey = (0, import_mcp_scope.currentMCPConnectionScopeKey)();
   if (scopeKey) parts.push(scopeKey);
   return parts.join("::");

package/dist/lib/protocols/mcp.mjs

@@ -19,7 +19,7 @@ import { buildAgentSigningFetch, signingContextStorage } from "../signing/client
 import { redactArgsForLog } from "../utils/redact-args.mjs";
 import { wrapFetchWithCapture } from "./rawResponseCapture.mjs";
 import { getSignedRequestRejection, wrapFetchWithSignedRequestRejection } from "./signedRequestRejection.mjs";
-import { wrapFetchWithSizeLimit } from "./responseSizeLimit.mjs";
+import { responseSizeCapCacheKey, wrapFetchWithSizeLimit } from "./responseSizeLimit.mjs";
 import { sanitizeTransportUrl, wrapFetchWithTransportDiagnostics } from "./transportDiagnostics.mjs";
 import {
   isAbortOrTimeoutError,
@@ -88,6 +88,7 @@ function connectionCacheKey(agentUrl, authToken, signingCacheKey, authHeaders, t
   if (signingCacheKey) parts.push(signingCacheKey);
   if (transportFetch) parts.push(`fetch:${getTransportFetchFnDisambiguator(transportFetch)}`);
   if (allowPrivateIp !== void 0) parts.push(`allow-private-ip:${allowPrivateIp}`);
+  parts.push(responseSizeCapCacheKey());
   const scopeKey = currentMCPConnectionScopeKey();
   if (scopeKey) parts.push(scopeKey);
   return parts.join("::");

package/dist/lib/protocols/responseSizeLimit.d.mts

@@ -1,23 +1,109 @@
+import { ResponseTooLargeError } from '../errors/index.mjs';
+/**
+ * Default response-body cap, in octets. Applied to every agent response on
+ * the MCP and A2A call paths (tool calls, discovery, `tools/list`, agent
+ * card) unless the caller overrides it.
+ *
+ * 4 MiB matches the hosted compliance grader's cap and the SDK's own probe
+ * caps. Raise it per client or per call with `transport.maxResponseBytes`
+ * when an agent legitimately publishes a large catalog.
+ */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * Multiplier applied to the per-response cap to derive the cumulative
+ * byte budget for `text/event-stream` responses in a single call.
+ *
+ * SSE needs two numbers, not one. The per-event cap is the memory bound —
+ * a consumer buffers one event frame before dispatching it, so no single
+ * event may exceed `maxResponseBytes`. The cumulative budget is the
+ * liveness bound — it stops a peer from holding a connection open and
+ * streaming forever in well-formed small frames.
+ *
+ * Deliberately small. Every multiple is a multiple a hostile peer can claim
+ * for free by putting `Content-Type: text/event-stream` on an ordinary reply
+ * and inserting a blank line every kilobyte, so the gap between the headline
+ * cap and the worst case an adopter can actually suffer should stay narrow.
+ * `2` leaves room for a normal tool call (many small status frames plus one
+ * result frame) without turning the advertised 4 MiB into 32 MiB.
+ */
+export declare const SSE_CUMULATIVE_BUDGET_MULTIPLIER = 2;
+/**
+ * Cumulative `text/event-stream` octets consumed so far. Shared by reference
+ * across nested `withResponseSizeLimit` scopes so a call spends one
+ * allowance, not one per SDK layer it passes through.
+ */
+interface StreamMeter {
+    consumed: number;
+}
 interface SizeLimitSlot {
-    maxResponseBytes: number;
+    /**
+     * Per-response cap in octets, or `null` when the caller explicitly opted
+     * out of enforcement for this scope.
+     */
+    maxResponseBytes: number | null;
+    /**
+     * Cumulative SSE allowance for this scope, in octets. Absent when
+     * enforcement is disabled.
+     */
+    streamLimit?: number;
+    /**
+     * Shared consumption counter for `text/event-stream` responses. Inherited
+     * from the enclosing scope so nesting narrows the allowance but never
+     * refills it. Absent when enforcement is disabled.
+     */
+    streamMeter?: StreamMeter;
+    /**
+     * First cap violation observed in this scope. A `TransformStream` error
+     * reaches whoever reads the body, and some transports swallow it: the MCP
+     * SDK treats a failed SSE read as a stream disconnect, retries, and lets
+     * the request time out. Recording the typed error here lets
+     * `withResponseSizeLimit` re-surface it instead of handing the caller an
+     * unrelated timeout. See `rethrowRecordedViolation`.
+     */
+    violation?: ResponseTooLargeError;
 }
 export declare const responseSizeLimitStorage: import("async_hooks").AsyncLocalStorage<SizeLimitSlot>;
 /**
  * Run `fn` with a response body byte cap active. Every fetch made through
  * a wrapped transport inside `fn` aborts with `ResponseTooLargeError` when
- * the response body exceeds `maxResponseBytes`. Non-positive caps disable
- * enforcement (ALS slot is not entered).
+ * the response body exceeds the cap.
+ *
+ * Passing `undefined` installs `DEFAULT_MAX_RESPONSE_BYTES` — unless an
+ * enclosing scope already set one, in which case the enclosing cap and its
+ * cumulative SSE allowance are inherited. More generally, **nesting only ever
+ * tightens**: both numbers take the minimum of the enclosing scope's and the
+ * new one's, and the cumulative SSE meter is shared rather than refilled.
+ *
+ * Nested SDK layers re-enter this helper on the way down (`callTool` →
+ * `callMCPToolWithTasks`), normally with the same value. Narrow-only means an
+ * inner layer that wasn't handed the caller's `transport` can't widen a tight
+ * outer cap back to the default, and re-entering with the same number can't
+ * multiply the cumulative allowance by the nesting depth. Per-call vs
+ * constructor `transport` is resolved with `??` before any scope is entered,
+ * so a per-call override still beats the constructor exactly as documented.
+ *
+ * Passing exactly `0` is the explicit opt-out: the slot is entered with
+ * enforcement disabled so an enclosing scope's cap (and the default the fetch
+ * wrapper would otherwise apply) is suppressed for the duration. `Infinity`
+ * and negative numbers are *not* opt-outs — they fall back to the default.
  */
 export declare function withResponseSizeLimit<T>(maxResponseBytes: number | undefined, fn: () => Promise<T>): Promise<T>;
 /**
- * Wrap a fetch implementation so its responses honor the size cap from the
- * active `responseSizeLimitStorage` slot. Pass-through when no slot is set.
+ * Wrap a fetch implementation so its responses honor the response size cap.
+ *
+ * Uses the active `responseSizeLimitStorage` slot when there is one, and
+ * `DEFAULT_MAX_RESPONSE_BYTES` when there isn't — the cap is on by default,
+ * not conditional on a caller having opened a scope. Only an explicit
+ * opt-out slot (`withResponseSizeLimit(0, …)`) disables it.
  *
  * Pre-checks `Content-Length` and refuses to read the body when the declared
  * size already exceeds the cap. Otherwise wraps `Response.body` in a
  * `TransformStream` that counts bytes and errors with `ResponseTooLargeError`
  * at the cap boundary, propagating to anyone reading the response (including
  * `Response.clone()` branches used by the diagnostic capture wrapper).
+ *
+ * `text/event-stream` responses are enforced too, with a per-event cap and a
+ * cumulative per-call budget — see `enforceEventStreamLimit`.
  */
 export declare function wrapFetchWithSizeLimit(upstream: typeof fetch): typeof fetch;
 export {};

package/dist/lib/protocols/responseSizeLimit.d.ts

@@ -1,23 +1,109 @@
+import { ResponseTooLargeError } from '../errors';
+/**
+ * Default response-body cap, in octets. Applied to every agent response on
+ * the MCP and A2A call paths (tool calls, discovery, `tools/list`, agent
+ * card) unless the caller overrides it.
+ *
+ * 4 MiB matches the hosted compliance grader's cap and the SDK's own probe
+ * caps. Raise it per client or per call with `transport.maxResponseBytes`
+ * when an agent legitimately publishes a large catalog.
+ */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * Multiplier applied to the per-response cap to derive the cumulative
+ * byte budget for `text/event-stream` responses in a single call.
+ *
+ * SSE needs two numbers, not one. The per-event cap is the memory bound —
+ * a consumer buffers one event frame before dispatching it, so no single
+ * event may exceed `maxResponseBytes`. The cumulative budget is the
+ * liveness bound — it stops a peer from holding a connection open and
+ * streaming forever in well-formed small frames.
+ *
+ * Deliberately small. Every multiple is a multiple a hostile peer can claim
+ * for free by putting `Content-Type: text/event-stream` on an ordinary reply
+ * and inserting a blank line every kilobyte, so the gap between the headline
+ * cap and the worst case an adopter can actually suffer should stay narrow.
+ * `2` leaves room for a normal tool call (many small status frames plus one
+ * result frame) without turning the advertised 4 MiB into 32 MiB.
+ */
+export declare const SSE_CUMULATIVE_BUDGET_MULTIPLIER = 2;
+/**
+ * Cumulative `text/event-stream` octets consumed so far. Shared by reference
+ * across nested `withResponseSizeLimit` scopes so a call spends one
+ * allowance, not one per SDK layer it passes through.
+ */
+interface StreamMeter {
+    consumed: number;
+}
 interface SizeLimitSlot {
-    maxResponseBytes: number;
+    /**
+     * Per-response cap in octets, or `null` when the caller explicitly opted
+     * out of enforcement for this scope.
+     */
+    maxResponseBytes: number | null;
+    /**
+     * Cumulative SSE allowance for this scope, in octets. Absent when
+     * enforcement is disabled.
+     */
+    streamLimit?: number;
+    /**
+     * Shared consumption counter for `text/event-stream` responses. Inherited
+     * from the enclosing scope so nesting narrows the allowance but never
+     * refills it. Absent when enforcement is disabled.
+     */
+    streamMeter?: StreamMeter;
+    /**
+     * First cap violation observed in this scope. A `TransformStream` error
+     * reaches whoever reads the body, and some transports swallow it: the MCP
+     * SDK treats a failed SSE read as a stream disconnect, retries, and lets
+     * the request time out. Recording the typed error here lets
+     * `withResponseSizeLimit` re-surface it instead of handing the caller an
+     * unrelated timeout. See `rethrowRecordedViolation`.
+     */
+    violation?: ResponseTooLargeError;
 }
 export declare const responseSizeLimitStorage: import("async_hooks").AsyncLocalStorage<SizeLimitSlot>;
 /**
  * Run `fn` with a response body byte cap active. Every fetch made through
  * a wrapped transport inside `fn` aborts with `ResponseTooLargeError` when
- * the response body exceeds `maxResponseBytes`. Non-positive caps disable
- * enforcement (ALS slot is not entered).
+ * the response body exceeds the cap.
+ *
+ * Passing `undefined` installs `DEFAULT_MAX_RESPONSE_BYTES` — unless an
+ * enclosing scope already set one, in which case the enclosing cap and its
+ * cumulative SSE allowance are inherited. More generally, **nesting only ever
+ * tightens**: both numbers take the minimum of the enclosing scope's and the
+ * new one's, and the cumulative SSE meter is shared rather than refilled.
+ *
+ * Nested SDK layers re-enter this helper on the way down (`callTool` →
+ * `callMCPToolWithTasks`), normally with the same value. Narrow-only means an
+ * inner layer that wasn't handed the caller's `transport` can't widen a tight
+ * outer cap back to the default, and re-entering with the same number can't
+ * multiply the cumulative allowance by the nesting depth. Per-call vs
+ * constructor `transport` is resolved with `??` before any scope is entered,
+ * so a per-call override still beats the constructor exactly as documented.
+ *
+ * Passing exactly `0` is the explicit opt-out: the slot is entered with
+ * enforcement disabled so an enclosing scope's cap (and the default the fetch
+ * wrapper would otherwise apply) is suppressed for the duration. `Infinity`
+ * and negative numbers are *not* opt-outs — they fall back to the default.
  */
 export declare function withResponseSizeLimit<T>(maxResponseBytes: number | undefined, fn: () => Promise<T>): Promise<T>;
 /**
- * Wrap a fetch implementation so its responses honor the size cap from the
- * active `responseSizeLimitStorage` slot. Pass-through when no slot is set.
+ * Wrap a fetch implementation so its responses honor the response size cap.
+ *
+ * Uses the active `responseSizeLimitStorage` slot when there is one, and
+ * `DEFAULT_MAX_RESPONSE_BYTES` when there isn't — the cap is on by default,
+ * not conditional on a caller having opened a scope. Only an explicit
+ * opt-out slot (`withResponseSizeLimit(0, …)`) disables it.
  *
  * Pre-checks `Content-Length` and refuses to read the body when the declared
  * size already exceeds the cap. Otherwise wraps `Response.body` in a
  * `TransformStream` that counts bytes and errors with `ResponseTooLargeError`
  * at the cap boundary, propagating to anyone reading the response (including
  * `Response.clone()` branches used by the diagnostic capture wrapper).
+ *
+ * `text/event-stream` responses are enforced too, with a per-event cap and a
+ * cumulative per-call budget — see `enforceEventStreamLimit`.
  */
 export declare function wrapFetchWithSizeLimit(upstream: typeof fetch): typeof fetch;
 export {};