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

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 {};

package/dist/lib/protocols/responseSizeLimit.js

@@ -18,6 +18,9 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var responseSizeLimit_exports = {};
 __export(responseSizeLimit_exports, {
+  DEFAULT_MAX_RESPONSE_BYTES: () => DEFAULT_MAX_RESPONSE_BYTES,
+  SSE_CUMULATIVE_BUDGET_MULTIPLIER: () => SSE_CUMULATIVE_BUDGET_MULTIPLIER,
+  responseSizeCapCacheKey: () => responseSizeCapCacheKey,
   responseSizeLimitStorage: () => responseSizeLimitStorage,
   withResponseSizeLimit: () => withResponseSizeLimit,
   wrapFetchWithSizeLimit: () => wrapFetchWithSizeLimit
@@ -25,52 +28,116 @@ __export(responseSizeLimit_exports, {
 module.exports = __toCommonJS(responseSizeLimit_exports);
 var import_global_async_local_storage = require('../utils/global-async-local-storage.js');
 var import_errors = require('../errors/index.js');
+var import_transportDiagnostics = require('./transportDiagnostics.js');
+const DEFAULT_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const SSE_CUMULATIVE_BUDGET_MULTIPLIER = 2;
 const responseSizeLimitStorage = (0, import_global_async_local_storage.globalAsyncLocalStorage)("responseSizeLimit");
+function resolveResponseSizeCap(maxResponseBytes) {
+  if (maxResponseBytes === void 0) return DEFAULT_MAX_RESPONSE_BYTES;
+  if (maxResponseBytes === 0) return null;
+  if (!Number.isFinite(maxResponseBytes) || maxResponseBytes < 0) return DEFAULT_MAX_RESPONSE_BYTES;
+  return maxResponseBytes;
+}
+function newSlot(maxResponseBytes) {
+  const resolved = resolveResponseSizeCap(maxResponseBytes);
+  if (resolved === null) return { maxResponseBytes: null };
+  const enclosing = responseSizeLimitStorage.getStore();
+  const limit = sseBudgetFor(resolved);
+  return {
+    // Nesting narrows both numbers. `?? resolved` deliberately also covers an
+    // enclosing opt-out (`null`): an inner scope that asks for a cap is the
+    // more specific instruction, so it still gets one.
+    maxResponseBytes: Math.min(resolved, enclosing?.maxResponseBytes ?? resolved),
+    streamLimit: Math.min(limit, enclosing?.streamLimit ?? limit),
+    streamMeter: enclosing?.streamMeter ?? { consumed: 0 }
+  };
+}
+function sseBudgetFor(maxResponseBytes) {
+  return Math.min(maxResponseBytes * SSE_CUMULATIVE_BUDGET_MULTIPLIER, Number.MAX_SAFE_INTEGER);
+}
+function responseSizeCapCacheKey() {
+  const slot = responseSizeLimitStorage.getStore();
+  const cap = slot ? slot.maxResponseBytes : DEFAULT_MAX_RESPONSE_BYTES;
+  return `max-response-bytes:${cap === null ? "off" : cap}`;
+}
 function withResponseSizeLimit(maxResponseBytes, fn) {
-  if (!maxResponseBytes || !Number.isFinite(maxResponseBytes) || maxResponseBytes <= 0) {
+  if (maxResponseBytes === void 0 && responseSizeLimitStorage.getStore()) {
     return fn();
   }
-  return responseSizeLimitStorage.run({ maxResponseBytes }, fn);
+  const slot = newSlot(maxResponseBytes);
+  return responseSizeLimitStorage.run(slot, () => rethrowRecordedViolation(slot, fn));
+}
+async function rethrowRecordedViolation(slot, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    const violation = slot.violation;
+    if (!violation || error instanceof import_errors.ResponseTooLargeError) throw error;
+    const surfaced = new import_errors.ResponseTooLargeError(
+      violation.limit,
+      violation.bytesRead,
+      violation.url,
+      violation.contentLengthHeader
+    );
+    Object.defineProperty(surfaced, "cause", { value: error, configurable: true });
+    throw surfaced;
+  }
+}
+function recordViolation(slot, error) {
+  if (slot && !slot.violation) slot.violation = error;
+  return error;
 }
 function urlOfInput(input) {
   if (typeof input === "string") return input;
   if (input instanceof URL) return input.toString();
   return input.url;
 }
-function redactUrlForError(url) {
-  try {
-    const parsed = new URL(url);
-    parsed.search = "";
-    return parsed.toString();
-  } catch {
-    return url;
-  }
-}
-function withIdentityEncoding(init) {
-  const headers = new Headers(init?.headers);
-  if (!headers.has("accept-encoding")) {
-    headers.set("accept-encoding", "identity");
-  }
-  return { ...init ?? {}, headers };
-}
 function wrapFetchWithSizeLimit(upstream) {
   const wrapped = async (input, init) => {
     const slot = responseSizeLimitStorage.getStore();
-    if (!slot) return upstream(input, init);
-    const response = await upstream(input, withIdentityEncoding(init));
-    return enforceSizeLimit(response, slot.maxResponseBytes, redactUrlForError(urlOfInput(input)));
+    const maxBytes = slot ? slot.maxResponseBytes : DEFAULT_MAX_RESPONSE_BYTES;
+    if (maxBytes === null) return upstream(input, init);
+    const response = await upstream(input, init);
+    if (NULL_BODY_STATUSES.has(response.status)) return response;
+    const skipDeclaredLength = methodOf(input, init) === "HEAD";
+    const url = (0, import_transportDiagnostics.sanitizeTransportUrl)(urlOfInput(input));
+    if (isEventStream(response)) {
+      const connectionScoped = methodOf(input, init) === "GET";
+      const { limit, meter } = streamBudgetFor(connectionScoped, slot, maxBytes);
+      return enforceEventStreamLimit(
+        response,
+        maxBytes,
+        limit,
+        meter,
+        url,
+        connectionScoped ? void 0 : slot,
+        skipDeclaredLength
+      );
+    }
+    return enforceSizeLimit(response, maxBytes, url, slot, skipDeclaredLength);
   };
   return wrapped;
 }
-function enforceSizeLimit(response, maxBytes, url) {
-  if (response.headers.get("content-type")?.toLowerCase().startsWith("text/event-stream")) {
-    return response;
-  }
-  const declared = parseContentLength(response.headers.get("content-length"));
+function streamBudgetFor(connectionScoped, slot, maxBytes) {
+  if (connectionScoped) return { limit: sseBudgetFor(maxBytes), meter: { consumed: 0 } };
+  return {
+    limit: slot?.streamLimit ?? sseBudgetFor(maxBytes),
+    meter: slot?.streamMeter ?? { consumed: 0 }
+  };
+}
+function methodOf(input, init) {
+  const method = init?.method ?? (typeof Request !== "undefined" && input instanceof Request ? input.method : "GET");
+  return method.toUpperCase();
+}
+const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([101, 103, 204, 205, 304]);
+function isEventStream(response) {
+  return response.headers.get("content-type")?.toLowerCase().startsWith("text/event-stream") === true;
+}
+function enforceSizeLimit(response, maxBytes, url, slot, skipDeclaredLength = false) {
+  const declared = skipDeclaredLength ? void 0 : parseContentLength(response.headers.get("content-length"));
   if (declared !== void 0 && declared > maxBytes) {
-    response.body?.cancel().catch(() => {
-    });
-    throw new import_errors.ResponseTooLargeError(maxBytes, 0, url, declared);
+    cancelBody(response);
+    throw recordViolation(slot, new import_errors.ResponseTooLargeError(maxBytes, 0, url, declared));
   }
   if (!response.body) return response;
   let bytesRead = 0;
@@ -78,13 +145,107 @@ function enforceSizeLimit(response, maxBytes, url) {
     transform(chunk, controller) {
       bytesRead += chunk.byteLength;
       if (bytesRead > maxBytes) {
-        controller.error(new import_errors.ResponseTooLargeError(maxBytes, bytesRead, url));
+        controller.error(recordViolation(slot, new import_errors.ResponseTooLargeError(maxBytes, bytesRead, url)));
         return;
       }
       controller.enqueue(chunk);
     }
   });
-  return new Response(response.body.pipeThrough(counter), {
+  return respondWith(response, response.body.pipeThrough(counter));
+}
+const CR = 13;
+const LF = 10;
+function enforceEventStreamLimit(response, maxBytes, streamLimit, meter, url, slot, skipDeclaredLength = false) {
+  const remaining = streamLimit - meter.consumed;
+  const declared = skipDeclaredLength ? void 0 : parseContentLength(response.headers.get("content-length"));
+  if (declared !== void 0 && declared > remaining) {
+    cancelBody(response);
+    throw recordViolation(slot, new import_errors.ResponseTooLargeError(streamLimit, meter.consumed, url, declared));
+  }
+  if (!response.body) return response;
+  let bytesInEvent = 0;
+  let lineEndings = 0;
+  let pendingCR = false;
+  let separatorTail = false;
+  let pendingReset = false;
+  const counter = new TransformStream({
+    transform(chunk, controller) {
+      meter.consumed += chunk.byteLength;
+      if (meter.consumed > streamLimit) {
+        controller.error(recordViolation(slot, new import_errors.ResponseTooLargeError(streamLimit, meter.consumed, url)));
+        return;
+      }
+      if (chunk.length === 0) {
+        controller.enqueue(chunk);
+        return;
+      }
+      if (chunk.indexOf(LF) === -1 && chunk.indexOf(CR) === -1) {
+        if (pendingReset) {
+          pendingReset = false;
+          separatorTail = false;
+          bytesInEvent = 0;
+        }
+        bytesInEvent += chunk.length;
+        lineEndings = 0;
+        pendingCR = false;
+        if (bytesInEvent > maxBytes) {
+          controller.error(recordViolation(slot, new import_errors.ResponseTooLargeError(maxBytes, bytesInEvent, url)));
+          return;
+        }
+        controller.enqueue(chunk);
+        return;
+      }
+      for (let i = 0; i < chunk.length; i += 1) {
+        const byte = chunk[i];
+        if (pendingReset) {
+          pendingReset = false;
+          if (separatorTail && byte === LF) {
+            separatorTail = false;
+            pendingCR = false;
+            bytesInEvent += 1;
+            if (bytesInEvent > maxBytes) {
+              controller.error(recordViolation(slot, new import_errors.ResponseTooLargeError(maxBytes, bytesInEvent, url)));
+              return;
+            }
+            bytesInEvent = 0;
+            continue;
+          }
+          separatorTail = false;
+          bytesInEvent = 0;
+        }
+        bytesInEvent += 1;
+        if (byte === CR) {
+          lineEndings += 1;
+          pendingCR = true;
+        } else if (byte === LF) {
+          if (!pendingCR) lineEndings += 1;
+          pendingCR = false;
+        } else {
+          lineEndings = 0;
+          pendingCR = false;
+        }
+        if (bytesInEvent > maxBytes) {
+          controller.error(recordViolation(slot, new import_errors.ResponseTooLargeError(maxBytes, bytesInEvent, url)));
+          return;
+        }
+        if (lineEndings >= 2) {
+          lineEndings = 0;
+          pendingReset = true;
+          separatorTail = pendingCR;
+          pendingCR = false;
+        }
+      }
+      controller.enqueue(chunk);
+    }
+  });
+  return respondWith(response, response.body.pipeThrough(counter));
+}
+function cancelBody(response) {
+  response.body?.cancel().catch(() => {
+  });
+}
+function respondWith(response, body) {
+  return new Response(body, {
     status: response.status,
     statusText: response.statusText,
     headers: response.headers
@@ -99,6 +260,9 @@ function parseContentLength(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_MAX_RESPONSE_BYTES,
+  SSE_CUMULATIVE_BUDGET_MULTIPLIER,
+  responseSizeCapCacheKey,
   responseSizeLimitStorage,
   withResponseSizeLimit,
   wrapFetchWithSizeLimit