@adcp/sdk 15.4.0 → 15.5.0

package/dist/lib/protocols/mcp-call-context.d.mts

@@ -0,0 +1,109 @@
+/**
+ * Per-call context for MCP connections that are shared between calls.
+ *
+ * A reusable MCP session must be keyed only by what changes the *connection*:
+ * endpoint, credential, tenant/routing headers, signing identity and transport
+ * policy. Correlation headers (`x-request-id`, `traceparent`, ...), the caller's
+ * `AbortSignal` and the per-call timeout describe one *call*. They are carried
+ * in an `AsyncLocalStorage` store and applied by the transport fetch on every
+ * request, so concurrent calls over one session never see each other's values.
+ */
+export interface MCPCallContext {
+    /** Correlation-only headers applied to every request made inside this call. */
+    headers?: Record<string, string>;
+    /** Cancellation for this call's own POST requests; set by {@link runCallPhase}. */
+    callSignal?: AbortSignal;
+    /** Per-call request timeout (already resolved; `undefined` means no SDK-imposed cap). */
+    requestTimeoutMs?: number;
+}
+export declare function runWithMCPCallContext<T>(context: MCPCallContext, fn: () => T): T;
+export declare function currentMCPCallContext(): MCPCallContext | undefined;
+/** Is this header a transient per-request correlation header (excluded from connection identity)? */
+export declare function isCorrelationHeader(name: string): boolean;
+/** Snapshot ambient routing headers before choosing a connection or discovery key. */
+export declare function withAmbientIdentityHeaders(headers?: Record<string, string>): Record<string, string>;
+/**
+ * Split a header bag into the headers that define the connection and the
+ * correlation headers that are sent per request.
+ */
+export declare function splitConnectionHeaders(headers: Record<string, string> | undefined): {
+    identity: Record<string, string>;
+    perRequest: Record<string, string>;
+};
+/**
+ * Apply correlation headers to an outgoing request. Inside a call context the
+ * active call's headers apply (and only those, so a shared session never leaks
+ * another caller's values). With no active call — a caller who owns the
+ * connection directly — the headers configured on that connection apply.
+ */
+export declare function applyMCPCallHeaders(headers: Headers, directDefaults?: Record<string, string>): void;
+/**
+ * Run one call over a shared connection while counting it as a user of that
+ * connection, so a failure in one call can retire the session without closing
+ * it underneath other in-flight calls.
+ */
+export declare function trackConnectionUse<T>(client: object, fn: () => Promise<T>): Promise<T>;
+/**
+ * Close a connection that must no longer be used: immediately when idle,
+ * otherwise once the last in-flight call has finished.
+ */
+export declare function closeWhenIdle(client: object, close: () => Promise<void>): Promise<void>;
+/** Bounded retries for joiners whose shared connect was cancelled by its creator. */
+export declare const MAX_FOREIGN_ABORT_RETRIES = 2;
+export declare const RETRY_CONNECT: unique symbol;
+/**
+ * Wait for a connect another caller started, under *this* caller's signal and
+ * timeout. The creator's cancellation or deadline belongs to the creator: when
+ * the shared connect fails that way, resolve `RETRY_CONNECT` so this caller
+ * connects for itself instead of inheriting someone else's abort. This
+ * caller's own abort or timeout still rejects.
+ */
+export declare function joinPendingConnection<T>(pending: Promise<T>, caller: {
+    signal?: AbortSignal;
+    requestTimeoutMs?: number;
+}, attempt: number): Promise<T | typeof RETRY_CONNECT>;
+/**
+ * Give a call over a shared v1 session its own cancellable HTTP scope. Every
+ * request the call makes (its POSTs and any `Last-Event-ID` stream resumption)
+ * observes one per-call signal, which fires when the caller's own signal does
+ * and, regardless of outcome, once the call settles. A call that is aborted, or
+ * that the v1 client timed out on while its HTTP request was still open, so
+ * leaves nothing running on the shared session, which stays usable by others.
+ *
+ * No deadline is applied here: the v1 client's per-request timeout resets on
+ * progress, so an absolute timer would cut a long-running Tasks stream.
+ *
+ * Only this call's requests observe the signal (`callRequestSignal`). The
+ * transport's long-lived background GET/SSE listener is created at connect
+ * time, outside this phase, and keeps its own lifetime.
+ */
+/** Internal cleanup of a response stream after the SDK has delivered a successful result. */
+declare const MCP_CALL_COMPLETED_MARKER: unique symbol;
+export declare const MCP_CALL_COMPLETED: DOMException & {
+    [MCP_CALL_COMPLETED_MARKER]: boolean;
+};
+/** Recognize the cleanup reason across independently bundled CJS/ESM entry points. */
+export declare function isMCPCallCompleted(reason: unknown): boolean;
+export declare function runCallPhase<T>(signal: AbortSignal | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * The active call's cancellation signal for its own requests: POSTs, and the
+ * `Last-Event-ID` GET that resumes a dropped response stream for that call.
+ */
+export declare function callRequestSignal(init: RequestInit | undefined): AbortSignal | undefined;
+/**
+ * Deadline for one HTTP request: the active call's timeout, or `fallback` when
+ * no call context is active (a direct caller who owns the connection). The
+ * transport's background GET/SSE listener is long-lived by design and is never
+ * given a per-call deadline.
+ */
+export declare function requestTimeoutFor(init: RequestInit | undefined, fallback?: number): number | undefined;
+/**
+ * `{ signal }` for an outgoing request: the request's own signal combined with
+ * the active call's. Applied at the outermost transport wrapper so every layer
+ * below (diagnostics, signing, network) observes the call's cancellation and
+ * classifies the stream as aborted, rather than seeing only a raw network abort.
+ */
+export declare function linkedCallSignal(init: RequestInit | undefined): {
+    signal?: AbortSignal;
+};
+export {};

package/dist/lib/protocols/mcp-call-context.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Per-call context for MCP connections that are shared between calls.
+ *
+ * A reusable MCP session must be keyed only by what changes the *connection*:
+ * endpoint, credential, tenant/routing headers, signing identity and transport
+ * policy. Correlation headers (`x-request-id`, `traceparent`, ...), the caller's
+ * `AbortSignal` and the per-call timeout describe one *call*. They are carried
+ * in an `AsyncLocalStorage` store and applied by the transport fetch on every
+ * request, so concurrent calls over one session never see each other's values.
+ */
+export interface MCPCallContext {
+    /** Correlation-only headers applied to every request made inside this call. */
+    headers?: Record<string, string>;
+    /** Cancellation for this call's own POST requests; set by {@link runCallPhase}. */
+    callSignal?: AbortSignal;
+    /** Per-call request timeout (already resolved; `undefined` means no SDK-imposed cap). */
+    requestTimeoutMs?: number;
+}
+export declare function runWithMCPCallContext<T>(context: MCPCallContext, fn: () => T): T;
+export declare function currentMCPCallContext(): MCPCallContext | undefined;
+/** Is this header a transient per-request correlation header (excluded from connection identity)? */
+export declare function isCorrelationHeader(name: string): boolean;
+/** Snapshot ambient routing headers before choosing a connection or discovery key. */
+export declare function withAmbientIdentityHeaders(headers?: Record<string, string>): Record<string, string>;
+/**
+ * Split a header bag into the headers that define the connection and the
+ * correlation headers that are sent per request.
+ */
+export declare function splitConnectionHeaders(headers: Record<string, string> | undefined): {
+    identity: Record<string, string>;
+    perRequest: Record<string, string>;
+};
+/**
+ * Apply correlation headers to an outgoing request. Inside a call context the
+ * active call's headers apply (and only those, so a shared session never leaks
+ * another caller's values). With no active call — a caller who owns the
+ * connection directly — the headers configured on that connection apply.
+ */
+export declare function applyMCPCallHeaders(headers: Headers, directDefaults?: Record<string, string>): void;
+/**
+ * Run one call over a shared connection while counting it as a user of that
+ * connection, so a failure in one call can retire the session without closing
+ * it underneath other in-flight calls.
+ */
+export declare function trackConnectionUse<T>(client: object, fn: () => Promise<T>): Promise<T>;
+/**
+ * Close a connection that must no longer be used: immediately when idle,
+ * otherwise once the last in-flight call has finished.
+ */
+export declare function closeWhenIdle(client: object, close: () => Promise<void>): Promise<void>;
+/** Bounded retries for joiners whose shared connect was cancelled by its creator. */
+export declare const MAX_FOREIGN_ABORT_RETRIES = 2;
+export declare const RETRY_CONNECT: unique symbol;
+/**
+ * Wait for a connect another caller started, under *this* caller's signal and
+ * timeout. The creator's cancellation or deadline belongs to the creator: when
+ * the shared connect fails that way, resolve `RETRY_CONNECT` so this caller
+ * connects for itself instead of inheriting someone else's abort. This
+ * caller's own abort or timeout still rejects.
+ */
+export declare function joinPendingConnection<T>(pending: Promise<T>, caller: {
+    signal?: AbortSignal;
+    requestTimeoutMs?: number;
+}, attempt: number): Promise<T | typeof RETRY_CONNECT>;
+/**
+ * Give a call over a shared v1 session its own cancellable HTTP scope. Every
+ * request the call makes (its POSTs and any `Last-Event-ID` stream resumption)
+ * observes one per-call signal, which fires when the caller's own signal does
+ * and, regardless of outcome, once the call settles. A call that is aborted, or
+ * that the v1 client timed out on while its HTTP request was still open, so
+ * leaves nothing running on the shared session, which stays usable by others.
+ *
+ * No deadline is applied here: the v1 client's per-request timeout resets on
+ * progress, so an absolute timer would cut a long-running Tasks stream.
+ *
+ * Only this call's requests observe the signal (`callRequestSignal`). The
+ * transport's long-lived background GET/SSE listener is created at connect
+ * time, outside this phase, and keeps its own lifetime.
+ */
+/** Internal cleanup of a response stream after the SDK has delivered a successful result. */
+declare const MCP_CALL_COMPLETED_MARKER: unique symbol;
+export declare const MCP_CALL_COMPLETED: DOMException & {
+    [MCP_CALL_COMPLETED_MARKER]: boolean;
+};
+/** Recognize the cleanup reason across independently bundled CJS/ESM entry points. */
+export declare function isMCPCallCompleted(reason: unknown): boolean;
+export declare function runCallPhase<T>(signal: AbortSignal | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * The active call's cancellation signal for its own requests: POSTs, and the
+ * `Last-Event-ID` GET that resumes a dropped response stream for that call.
+ */
+export declare function callRequestSignal(init: RequestInit | undefined): AbortSignal | undefined;
+/**
+ * Deadline for one HTTP request: the active call's timeout, or `fallback` when
+ * no call context is active (a direct caller who owns the connection). The
+ * transport's background GET/SSE listener is long-lived by design and is never
+ * given a per-call deadline.
+ */
+export declare function requestTimeoutFor(init: RequestInit | undefined, fallback?: number): number | undefined;
+/**
+ * `{ signal }` for an outgoing request: the request's own signal combined with
+ * the active call's. Applied at the outermost transport wrapper so every layer
+ * below (diagnostics, signing, network) observes the call's cancellation and
+ * classifies the stream as aborted, rather than seeing only a raw network abort.
+ */
+export declare function linkedCallSignal(init: RequestInit | undefined): {
+    signal?: AbortSignal;
+};
+export {};

package/dist/lib/protocols/mcp-call-context.js

@@ -0,0 +1,221 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var mcp_call_context_exports = {};
+__export(mcp_call_context_exports, {
+  MAX_FOREIGN_ABORT_RETRIES: () => MAX_FOREIGN_ABORT_RETRIES,
+  MCP_CALL_COMPLETED: () => MCP_CALL_COMPLETED,
+  RETRY_CONNECT: () => RETRY_CONNECT,
+  applyMCPCallHeaders: () => applyMCPCallHeaders,
+  callRequestSignal: () => callRequestSignal,
+  closeWhenIdle: () => closeWhenIdle,
+  currentMCPCallContext: () => currentMCPCallContext,
+  isCorrelationHeader: () => isCorrelationHeader,
+  isMCPCallCompleted: () => isMCPCallCompleted,
+  joinPendingConnection: () => joinPendingConnection,
+  linkedCallSignal: () => linkedCallSignal,
+  requestTimeoutFor: () => requestTimeoutFor,
+  runCallPhase: () => runCallPhase,
+  runWithMCPCallContext: () => runWithMCPCallContext,
+  splitConnectionHeaders: () => splitConnectionHeaders,
+  trackConnectionUse: () => trackConnectionUse,
+  withAmbientIdentityHeaders: () => withAmbientIdentityHeaders
+});
+module.exports = __toCommonJS(mcp_call_context_exports);
+var import_node_async_hooks = require("node:async_hooks");
+var import_tracing = require('../observability/tracing.js');
+var import_abort = require('./abort.js');
+const callContextStorage = new import_node_async_hooks.AsyncLocalStorage();
+function runWithMCPCallContext(context, fn) {
+  return callContextStorage.run(context, fn);
+}
+function currentMCPCallContext() {
+  return callContextStorage.getStore();
+}
+const CORRELATION_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "traceparent",
+  "tracestate",
+  "sentry-trace",
+  "b3",
+  "x-request-id",
+  "x-correlation-id",
+  "x-trace-id",
+  "x-span-id",
+  "x-debug-id",
+  "x-client-request-id",
+  "x-amzn-trace-id",
+  "x-cloud-trace-context",
+  "x-ms-client-request-id",
+  "x-b3-traceid",
+  "x-b3-spanid",
+  "x-b3-parentspanid",
+  "x-b3-sampled",
+  "x-b3-flags",
+  "x-datadog-trace-id",
+  "x-datadog-parent-id",
+  "x-datadog-sampling-priority",
+  "x-datadog-tags"
+]);
+const CORRELATION_HEADER_PATTERN = /^x-(?:[a-z0-9]+-)+(?:request|correlation|trace|span|debug)-id$/;
+const IDENTITY_HEADER_HINT = /auth|token|key|secret|cookie|session|tenant|account|org|user|principal|cred|signature|advertiser|workspace|seat|brand|buyer|seller|customer|network|publisher|property|route|routing|region|project|team/;
+function isCorrelationHeader(name) {
+  const lower = name.toLowerCase();
+  if (IDENTITY_HEADER_HINT.test(lower)) return false;
+  return CORRELATION_HEADER_NAMES.has(lower) || CORRELATION_HEADER_PATTERN.test(lower);
+}
+function withAmbientIdentityHeaders(headers) {
+  const effective = new Headers(headers);
+  if (!effective.has("traceparent")) {
+    for (const [name, value] of Object.entries((0, import_tracing.injectTraceHeaders)())) {
+      if (!isCorrelationHeader(name) && !effective.has(name)) effective.set(name, value);
+    }
+  }
+  const result = {};
+  effective.forEach((value, name) => {
+    result[name] = value;
+  });
+  return result;
+}
+function splitConnectionHeaders(headers) {
+  const identity = {};
+  const perRequest = {};
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    (isCorrelationHeader(key) ? perRequest : identity)[key] = value;
+  }
+  return { identity, perRequest };
+}
+function applyMCPCallHeaders(headers, directDefaults) {
+  const context = callContextStorage.getStore();
+  const perCall = context ? context.headers : directDefaults;
+  if (!perCall) return;
+  for (const [key, value] of Object.entries(perCall)) headers.set(key, value);
+}
+const connectionUse = /* @__PURE__ */ new WeakMap();
+async function trackConnectionUse(client, fn) {
+  let use = connectionUse.get(client);
+  if (!use) {
+    use = { active: 0 };
+    connectionUse.set(client, use);
+  }
+  use.active++;
+  try {
+    return await fn();
+  } finally {
+    use.active--;
+    if (use.active === 0 && use.retire) {
+      const retire = use.retire;
+      use.retire = void 0;
+      void retire().catch(() => {
+      });
+    }
+  }
+}
+async function closeWhenIdle(client, close) {
+  const use = connectionUse.get(client);
+  if (!use || use.active === 0) {
+    await close();
+    return;
+  }
+  use.retire = close;
+}
+const MAX_FOREIGN_ABORT_RETRIES = 2;
+const RETRY_CONNECT = /* @__PURE__ */ Symbol("retry-connect");
+async function joinPendingConnection(pending, caller, attempt) {
+  const settled = pending.then(
+    (value) => ({ value }),
+    (error) => ({ error })
+  );
+  const outcome = await (0, import_abort.withAbortSignal)(
+    [caller.signal],
+    (0, import_abort.resolveRequestTimeoutMs)(caller.requestTimeoutMs),
+    () => settled
+  );
+  if ("value" in outcome) return outcome.value;
+  if ((0, import_abort.isAbortOrTimeoutError)(outcome.error) && attempt < MAX_FOREIGN_ABORT_RETRIES) return RETRY_CONNECT;
+  throw outcome.error;
+}
+const MCP_CALL_COMPLETED_MARKER = /* @__PURE__ */ Symbol.for("@adcp/sdk/mcp-call-completed");
+const MCP_CALL_COMPLETED = Object.assign(new DOMException("MCP call completed", "AbortError"), {
+  [MCP_CALL_COMPLETED_MARKER]: true
+});
+function isMCPCallCompleted(reason) {
+  return typeof reason === "object" && reason !== null && reason[MCP_CALL_COMPLETED_MARKER] === true;
+}
+async function runCallPhase(signal, fn) {
+  const context = callContextStorage.getStore();
+  if (!context) return fn();
+  const controller = new AbortController();
+  const forward = () => controller.abort(signal?.reason);
+  if (signal?.aborted) forward();
+  else signal?.addEventListener("abort", forward, { once: true });
+  let completed = false;
+  try {
+    const result = await callContextStorage.run({ ...context, callSignal: controller.signal }, fn);
+    completed = true;
+    return result;
+  } finally {
+    signal?.removeEventListener("abort", forward);
+    controller.abort(completed ? MCP_CALL_COMPLETED : void 0);
+  }
+}
+const JSON_RPC_NOTIFICATION = /^\s*\{[^]{0,120}?"method"\s*:\s*"notifications\//;
+function isNotificationBody(body) {
+  if (!JSON_RPC_NOTIFICATION.test(body)) return false;
+  try {
+    const message = JSON.parse(body);
+    return message !== null && typeof message === "object" && !Array.isArray(message) && !Object.prototype.hasOwnProperty.call(message, "id") && typeof message.method === "string" && message.method.startsWith("notifications/");
+  } catch {
+    return false;
+  }
+}
+function callRequestSignal(init) {
+  const method = (init?.method ?? "GET").toUpperCase();
+  if (method !== "POST" && !(method === "GET" && new Headers(init?.headers).has("last-event-id"))) return void 0;
+  if (method === "POST" && typeof init?.body === "string" && isNotificationBody(init.body)) return void 0;
+  return callContextStorage.getStore()?.callSignal;
+}
+function requestTimeoutFor(init, fallback) {
+  if ((init?.method ?? "GET").toUpperCase() === "GET") return void 0;
+  const context = callContextStorage.getStore();
+  return context ? context.requestTimeoutMs : fallback;
+}
+function linkedCallSignal(init) {
+  const callSignal = callRequestSignal(init);
+  if (!callSignal) return {};
+  return { signal: init?.signal ? AbortSignal.any([init.signal, callSignal]) : callSignal };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MAX_FOREIGN_ABORT_RETRIES,
+  MCP_CALL_COMPLETED,
+  RETRY_CONNECT,
+  applyMCPCallHeaders,
+  callRequestSignal,
+  closeWhenIdle,
+  currentMCPCallContext,
+  isCorrelationHeader,
+  isMCPCallCompleted,
+  joinPendingConnection,
+  linkedCallSignal,
+  requestTimeoutFor,
+  runCallPhase,
+  runWithMCPCallContext,
+  splitConnectionHeaders,
+  trackConnectionUse,
+  withAmbientIdentityHeaders
+});

package/dist/lib/protocols/mcp-call-context.mjs

@@ -0,0 +1,186 @@
+import { fileURLToPath as __adcpFileURLToPath } from "node:url";
+import { dirname as __adcpDirname } from "node:path";
+import { createRequire as __adcpCreateRequire } from "node:module";
+const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
+const require2 = __adcpCreateRequire(import.meta.url);
+import { AsyncLocalStorage } from "node:async_hooks";
+import { injectTraceHeaders } from "../observability/tracing.mjs";
+import { isAbortOrTimeoutError, resolveRequestTimeoutMs, withAbortSignal } from "./abort.mjs";
+const callContextStorage = new AsyncLocalStorage();
+function runWithMCPCallContext(context, fn) {
+  return callContextStorage.run(context, fn);
+}
+function currentMCPCallContext() {
+  return callContextStorage.getStore();
+}
+const CORRELATION_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "traceparent",
+  "tracestate",
+  "sentry-trace",
+  "b3",
+  "x-request-id",
+  "x-correlation-id",
+  "x-trace-id",
+  "x-span-id",
+  "x-debug-id",
+  "x-client-request-id",
+  "x-amzn-trace-id",
+  "x-cloud-trace-context",
+  "x-ms-client-request-id",
+  "x-b3-traceid",
+  "x-b3-spanid",
+  "x-b3-parentspanid",
+  "x-b3-sampled",
+  "x-b3-flags",
+  "x-datadog-trace-id",
+  "x-datadog-parent-id",
+  "x-datadog-sampling-priority",
+  "x-datadog-tags"
+]);
+const CORRELATION_HEADER_PATTERN = /^x-(?:[a-z0-9]+-)+(?:request|correlation|trace|span|debug)-id$/;
+const IDENTITY_HEADER_HINT = /auth|token|key|secret|cookie|session|tenant|account|org|user|principal|cred|signature|advertiser|workspace|seat|brand|buyer|seller|customer|network|publisher|property|route|routing|region|project|team/;
+function isCorrelationHeader(name) {
+  const lower = name.toLowerCase();
+  if (IDENTITY_HEADER_HINT.test(lower)) return false;
+  return CORRELATION_HEADER_NAMES.has(lower) || CORRELATION_HEADER_PATTERN.test(lower);
+}
+function withAmbientIdentityHeaders(headers) {
+  const effective = new Headers(headers);
+  if (!effective.has("traceparent")) {
+    for (const [name, value] of Object.entries(injectTraceHeaders())) {
+      if (!isCorrelationHeader(name) && !effective.has(name)) effective.set(name, value);
+    }
+  }
+  const result = {};
+  effective.forEach((value, name) => {
+    result[name] = value;
+  });
+  return result;
+}
+function splitConnectionHeaders(headers) {
+  const identity = {};
+  const perRequest = {};
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    (isCorrelationHeader(key) ? perRequest : identity)[key] = value;
+  }
+  return { identity, perRequest };
+}
+function applyMCPCallHeaders(headers, directDefaults) {
+  const context = callContextStorage.getStore();
+  const perCall = context ? context.headers : directDefaults;
+  if (!perCall) return;
+  for (const [key, value] of Object.entries(perCall)) headers.set(key, value);
+}
+const connectionUse = /* @__PURE__ */ new WeakMap();
+async function trackConnectionUse(client, fn) {
+  let use = connectionUse.get(client);
+  if (!use) {
+    use = { active: 0 };
+    connectionUse.set(client, use);
+  }
+  use.active++;
+  try {
+    return await fn();
+  } finally {
+    use.active--;
+    if (use.active === 0 && use.retire) {
+      const retire = use.retire;
+      use.retire = void 0;
+      void retire().catch(() => {
+      });
+    }
+  }
+}
+async function closeWhenIdle(client, close) {
+  const use = connectionUse.get(client);
+  if (!use || use.active === 0) {
+    await close();
+    return;
+  }
+  use.retire = close;
+}
+const MAX_FOREIGN_ABORT_RETRIES = 2;
+const RETRY_CONNECT = /* @__PURE__ */ Symbol("retry-connect");
+async function joinPendingConnection(pending, caller, attempt) {
+  const settled = pending.then(
+    (value) => ({ value }),
+    (error) => ({ error })
+  );
+  const outcome = await withAbortSignal(
+    [caller.signal],
+    resolveRequestTimeoutMs(caller.requestTimeoutMs),
+    () => settled
+  );
+  if ("value" in outcome) return outcome.value;
+  if (isAbortOrTimeoutError(outcome.error) && attempt < MAX_FOREIGN_ABORT_RETRIES) return RETRY_CONNECT;
+  throw outcome.error;
+}
+const MCP_CALL_COMPLETED_MARKER = /* @__PURE__ */ Symbol.for("@adcp/sdk/mcp-call-completed");
+const MCP_CALL_COMPLETED = Object.assign(new DOMException("MCP call completed", "AbortError"), {
+  [MCP_CALL_COMPLETED_MARKER]: true
+});
+function isMCPCallCompleted(reason) {
+  return typeof reason === "object" && reason !== null && reason[MCP_CALL_COMPLETED_MARKER] === true;
+}
+async function runCallPhase(signal, fn) {
+  const context = callContextStorage.getStore();
+  if (!context) return fn();
+  const controller = new AbortController();
+  const forward = () => controller.abort(signal?.reason);
+  if (signal?.aborted) forward();
+  else signal?.addEventListener("abort", forward, { once: true });
+  let completed = false;
+  try {
+    const result = await callContextStorage.run({ ...context, callSignal: controller.signal }, fn);
+    completed = true;
+    return result;
+  } finally {
+    signal?.removeEventListener("abort", forward);
+    controller.abort(completed ? MCP_CALL_COMPLETED : void 0);
+  }
+}
+const JSON_RPC_NOTIFICATION = /^\s*\{[^]{0,120}?"method"\s*:\s*"notifications\//;
+function isNotificationBody(body) {
+  if (!JSON_RPC_NOTIFICATION.test(body)) return false;
+  try {
+    const message = JSON.parse(body);
+    return message !== null && typeof message === "object" && !Array.isArray(message) && !Object.prototype.hasOwnProperty.call(message, "id") && typeof message.method === "string" && message.method.startsWith("notifications/");
+  } catch {
+    return false;
+  }
+}
+function callRequestSignal(init) {
+  const method = (init?.method ?? "GET").toUpperCase();
+  if (method !== "POST" && !(method === "GET" && new Headers(init?.headers).has("last-event-id"))) return void 0;
+  if (method === "POST" && typeof init?.body === "string" && isNotificationBody(init.body)) return void 0;
+  return callContextStorage.getStore()?.callSignal;
+}
+function requestTimeoutFor(init, fallback) {
+  if ((init?.method ?? "GET").toUpperCase() === "GET") return void 0;
+  const context = callContextStorage.getStore();
+  return context ? context.requestTimeoutMs : fallback;
+}
+function linkedCallSignal(init) {
+  const callSignal = callRequestSignal(init);
+  if (!callSignal) return {};
+  return { signal: init?.signal ? AbortSignal.any([init.signal, callSignal]) : callSignal };
+}
+export {
+  MAX_FOREIGN_ABORT_RETRIES,
+  MCP_CALL_COMPLETED,
+  RETRY_CONNECT,
+  applyMCPCallHeaders,
+  callRequestSignal,
+  closeWhenIdle,
+  currentMCPCallContext,
+  isCorrelationHeader,
+  isMCPCallCompleted,
+  joinPendingConnection,
+  linkedCallSignal,
+  requestTimeoutFor,
+  runCallPhase,
+  runWithMCPCallContext,
+  splitConnectionHeaders,
+  trackConnectionUse,
+  withAmbientIdentityHeaders
+};

package/dist/lib/protocols/mcp-modern.d.mts

@@ -52,12 +52,20 @@ export declare function tryCallModernMCPTool(agentUrl: string, toolName: string,
 /**
  * Probe an endpoint with the official v2 client's auto negotiation.
  * `connected: false` lets endpoint discovery retain its v1 SSE fallback.
+ *
+ * Inside a caller-owned connection scope the negotiated session is the scope's
+ * shared session, so the probe, capability discovery and the tool calls that
+ * follow run over one `initialize`. Outside a scope the probe stays a fresh,
+ * self-closing negotiation.
  */
 export declare function probeModernMCPConnection(agentUrl: string, authToken?: string, customHeaders?: Record<string, string>, options?: ModernMCPConnectionOptions): Promise<{
     connected: boolean;
     era?: 'legacy' | 'modern';
 }>;
-/** List tools when the endpoint selected the modern era; otherwise let the v1 caller continue. */
+/**
+ * List tools when the endpoint selected the modern era (or, with `handleLegacy`,
+ * over the v2 client's negotiated legacy session); otherwise let the v1 caller continue.
+ */
 export declare function tryListModernMCPTools(agentUrl: string, authToken?: string, customHeaders?: Record<string, string>, options?: ModernMCPConnectionOptions): Promise<ModernMCPListAttempt>;
 export declare function closeModernMCPConnections(): Promise<void>;
 export {};

package/dist/lib/protocols/mcp-modern.d.ts

@@ -52,12 +52,20 @@ export declare function tryCallModernMCPTool(agentUrl: string, toolName: string,
 /**
  * Probe an endpoint with the official v2 client's auto negotiation.
  * `connected: false` lets endpoint discovery retain its v1 SSE fallback.
+ *
+ * Inside a caller-owned connection scope the negotiated session is the scope's
+ * shared session, so the probe, capability discovery and the tool calls that
+ * follow run over one `initialize`. Outside a scope the probe stays a fresh,
+ * self-closing negotiation.
  */
 export declare function probeModernMCPConnection(agentUrl: string, authToken?: string, customHeaders?: Record<string, string>, options?: ModernMCPConnectionOptions): Promise<{
     connected: boolean;
     era?: 'legacy' | 'modern';
 }>;
-/** List tools when the endpoint selected the modern era; otherwise let the v1 caller continue. */
+/**
+ * List tools when the endpoint selected the modern era (or, with `handleLegacy`,
+ * over the v2 client's negotiated legacy session); otherwise let the v1 caller continue.
+ */
 export declare function tryListModernMCPTools(agentUrl: string, authToken?: string, customHeaders?: Record<string, string>, options?: ModernMCPConnectionOptions): Promise<ModernMCPListAttempt>;
 export declare function closeModernMCPConnections(): Promise<void>;
 export {};