@adcp/sdk 15.4.0 → 15.5.0

package/dist/lib/core/agent-discovery-cache.d.mts

@@ -0,0 +1,103 @@
+import type { AdcpCapabilities } from '../utils/capabilities.mjs';
+/** Default freshness window for shared discovery entries. */
+export declare const DEFAULT_AGENT_DISCOVERY_TTL_MS: number;
+/** Upper bound for a configured TTL; shared entries are discovery hints, not durable state. */
+export declare const MAX_AGENT_DISCOVERY_TTL_MS: number;
+/**
+ * Endpoint, tool-list and capability evidence for one (agent, caller identity,
+ * AdCP version, transport policy) tuple. Entries are plain JSON so a shared
+ * cache can live in process memory or an external store.
+ */
+export interface AgentDiscoveryEntry {
+    /** MCP endpoint resolved by endpoint discovery (the URL actually serving MCP). */
+    endpoint?: {
+        agentUri: string;
+        mcpEra?: 'legacy' | 'modern';
+        /** Epoch milliseconds when this endpoint was observed (may be older than the entry). */
+        observedAt?: number;
+    };
+    /** Capabilities from an authoritative `get_adcp_capabilities` response. Never synthetic. */
+    capabilities?: AdcpCapabilities;
+    /** `tools/list` input-schema properties keyed by tool name. */
+    toolSchemas?: Record<string, Record<string, unknown>>;
+    /** Epoch milliseconds when this evidence was observed. */
+    observedAt: number;
+    /** Epoch milliseconds after which the entry must not be used. Enforced by the SDK on read. */
+    expiresAt: number;
+}
+/**
+ * Storage backend for shared discovery entries. Keys are opaque SHA-256
+ * digests derived by the SDK; implementations must not interpret them and
+ * must return copies (or immutable values) so callers cannot mutate stored
+ * entries. Methods may be synchronous or asynchronous.
+ */
+export interface AgentDiscoveryCache {
+    get(key: string): AgentDiscoveryEntry | undefined | Promise<AgentDiscoveryEntry | undefined>;
+    set(key: string, entry: AgentDiscoveryEntry): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+}
+/**
+ * Opt-in sharing of endpoint / `tools/list` / `get_adcp_capabilities`
+ * discovery across `SingleAgentClient` instances.
+ *
+ * Sharing is explicit: nothing is shared unless a client is configured with a
+ * cache AND a caller-owned `authIdentity`.
+ */
+export interface AgentDiscoveryCacheConfig {
+    /** Shared store. Create one with {@link createInMemoryAgentDiscoveryCache}. */
+    cache: AgentDiscoveryCache;
+    /**
+     * Stable, caller-owned identity of the principal whose credentials these
+     * clients use (for example a tenant or buyer-account ID). Required.
+     *
+     * Entries are only shared between clients that present the same identity, so
+     * choose it to be at least as specific as the credential's authorization
+     * scope. It is NOT derived from the token: rotating a token for the same
+     * principal keeps the entry, and two principals must never share an identity.
+     * The identity is hashed into the cache key and never stored in the entry.
+     */
+    authIdentity: string;
+    /** Freshness window in milliseconds. Defaults to five minutes; capped at 24 hours. */
+    ttlMs?: number;
+}
+export interface InMemoryAgentDiscoveryCacheOptions {
+    /** Maximum retained entries; least-recently-used entries are evicted. Defaults to 256. */
+    maxEntries?: number;
+}
+/** Process-local {@link AgentDiscoveryCache} with LRU eviction and copy-on-read/write. */
+export interface InMemoryAgentDiscoveryCache extends AgentDiscoveryCache {
+    get(key: string): AgentDiscoveryEntry | undefined;
+    set(key: string, entry: AgentDiscoveryEntry): void;
+    delete(key: string): void;
+    /** Drop every entry. */
+    clear(): void;
+    /** Number of retained entries (including entries that have expired but not been read). */
+    readonly size: number;
+}
+export declare function createInMemoryAgentDiscoveryCache(options?: InMemoryAgentDiscoveryCacheOptions): InMemoryAgentDiscoveryCache;
+/** Validate a client's shared-discovery configuration at construction time. */
+export declare function validateAgentDiscoveryCacheConfig(config: AgentDiscoveryCacheConfig | undefined): void;
+export declare function resolveAgentDiscoveryTtlMs(ttlMs: number | undefined): number;
+/** Everything that decides which cached discovery evidence a client may reuse. */
+export interface AgentDiscoveryKeyInput {
+    protocol: string;
+    agentUri: string;
+    adcpVersion: string;
+    wireAdcpVersion?: string;
+    authIdentity: string;
+    /** Kind of credential presented (`none`, `bearer`, `oauth`, `header`, ...); never its value. */
+    credentialKind?: string;
+    /** Request headers the client sends on every call (correlation and credential headers are dropped here). */
+    headers?: Record<string, string>;
+    /** Non-secret fingerprint of the request-signing identity, when configured. */
+    signing?: unknown;
+    allowPrivateIp?: boolean;
+    maxResponseBytes?: number;
+}
+/**
+ * Derive the opaque cache key. Correlation headers are excluded (they differ
+ * on every request) and so are credential headers (owned by `authIdentity`); every
+ * other header — including unknown tenant, routing and policy headers — is part of the key, as are the signing identity and the
+ * transport policy that governed how the evidence was collected.
+ */
+export declare function agentDiscoveryCacheKey(input: AgentDiscoveryKeyInput): string;

package/dist/lib/core/agent-discovery-cache.d.ts

@@ -0,0 +1,103 @@
+import type { AdcpCapabilities } from '../utils/capabilities';
+/** Default freshness window for shared discovery entries. */
+export declare const DEFAULT_AGENT_DISCOVERY_TTL_MS: number;
+/** Upper bound for a configured TTL; shared entries are discovery hints, not durable state. */
+export declare const MAX_AGENT_DISCOVERY_TTL_MS: number;
+/**
+ * Endpoint, tool-list and capability evidence for one (agent, caller identity,
+ * AdCP version, transport policy) tuple. Entries are plain JSON so a shared
+ * cache can live in process memory or an external store.
+ */
+export interface AgentDiscoveryEntry {
+    /** MCP endpoint resolved by endpoint discovery (the URL actually serving MCP). */
+    endpoint?: {
+        agentUri: string;
+        mcpEra?: 'legacy' | 'modern';
+        /** Epoch milliseconds when this endpoint was observed (may be older than the entry). */
+        observedAt?: number;
+    };
+    /** Capabilities from an authoritative `get_adcp_capabilities` response. Never synthetic. */
+    capabilities?: AdcpCapabilities;
+    /** `tools/list` input-schema properties keyed by tool name. */
+    toolSchemas?: Record<string, Record<string, unknown>>;
+    /** Epoch milliseconds when this evidence was observed. */
+    observedAt: number;
+    /** Epoch milliseconds after which the entry must not be used. Enforced by the SDK on read. */
+    expiresAt: number;
+}
+/**
+ * Storage backend for shared discovery entries. Keys are opaque SHA-256
+ * digests derived by the SDK; implementations must not interpret them and
+ * must return copies (or immutable values) so callers cannot mutate stored
+ * entries. Methods may be synchronous or asynchronous.
+ */
+export interface AgentDiscoveryCache {
+    get(key: string): AgentDiscoveryEntry | undefined | Promise<AgentDiscoveryEntry | undefined>;
+    set(key: string, entry: AgentDiscoveryEntry): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+}
+/**
+ * Opt-in sharing of endpoint / `tools/list` / `get_adcp_capabilities`
+ * discovery across `SingleAgentClient` instances.
+ *
+ * Sharing is explicit: nothing is shared unless a client is configured with a
+ * cache AND a caller-owned `authIdentity`.
+ */
+export interface AgentDiscoveryCacheConfig {
+    /** Shared store. Create one with {@link createInMemoryAgentDiscoveryCache}. */
+    cache: AgentDiscoveryCache;
+    /**
+     * Stable, caller-owned identity of the principal whose credentials these
+     * clients use (for example a tenant or buyer-account ID). Required.
+     *
+     * Entries are only shared between clients that present the same identity, so
+     * choose it to be at least as specific as the credential's authorization
+     * scope. It is NOT derived from the token: rotating a token for the same
+     * principal keeps the entry, and two principals must never share an identity.
+     * The identity is hashed into the cache key and never stored in the entry.
+     */
+    authIdentity: string;
+    /** Freshness window in milliseconds. Defaults to five minutes; capped at 24 hours. */
+    ttlMs?: number;
+}
+export interface InMemoryAgentDiscoveryCacheOptions {
+    /** Maximum retained entries; least-recently-used entries are evicted. Defaults to 256. */
+    maxEntries?: number;
+}
+/** Process-local {@link AgentDiscoveryCache} with LRU eviction and copy-on-read/write. */
+export interface InMemoryAgentDiscoveryCache extends AgentDiscoveryCache {
+    get(key: string): AgentDiscoveryEntry | undefined;
+    set(key: string, entry: AgentDiscoveryEntry): void;
+    delete(key: string): void;
+    /** Drop every entry. */
+    clear(): void;
+    /** Number of retained entries (including entries that have expired but not been read). */
+    readonly size: number;
+}
+export declare function createInMemoryAgentDiscoveryCache(options?: InMemoryAgentDiscoveryCacheOptions): InMemoryAgentDiscoveryCache;
+/** Validate a client's shared-discovery configuration at construction time. */
+export declare function validateAgentDiscoveryCacheConfig(config: AgentDiscoveryCacheConfig | undefined): void;
+export declare function resolveAgentDiscoveryTtlMs(ttlMs: number | undefined): number;
+/** Everything that decides which cached discovery evidence a client may reuse. */
+export interface AgentDiscoveryKeyInput {
+    protocol: string;
+    agentUri: string;
+    adcpVersion: string;
+    wireAdcpVersion?: string;
+    authIdentity: string;
+    /** Kind of credential presented (`none`, `bearer`, `oauth`, `header`, ...); never its value. */
+    credentialKind?: string;
+    /** Request headers the client sends on every call (correlation and credential headers are dropped here). */
+    headers?: Record<string, string>;
+    /** Non-secret fingerprint of the request-signing identity, when configured. */
+    signing?: unknown;
+    allowPrivateIp?: boolean;
+    maxResponseBytes?: number;
+}
+/**
+ * Derive the opaque cache key. Correlation headers are excluded (they differ
+ * on every request) and so are credential headers (owned by `authIdentity`); every
+ * other header — including unknown tenant, routing and policy headers — is part of the key, as are the signing identity and the
+ * transport policy that governed how the evidence was collected.
+ */
+export declare function agentDiscoveryCacheKey(input: AgentDiscoveryKeyInput): string;

package/dist/lib/core/agent-discovery-cache.js

@@ -0,0 +1,121 @@
+"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 agent_discovery_cache_exports = {};
+__export(agent_discovery_cache_exports, {
+  DEFAULT_AGENT_DISCOVERY_TTL_MS: () => DEFAULT_AGENT_DISCOVERY_TTL_MS,
+  MAX_AGENT_DISCOVERY_TTL_MS: () => MAX_AGENT_DISCOVERY_TTL_MS,
+  agentDiscoveryCacheKey: () => agentDiscoveryCacheKey,
+  createInMemoryAgentDiscoveryCache: () => createInMemoryAgentDiscoveryCache,
+  resolveAgentDiscoveryTtlMs: () => resolveAgentDiscoveryTtlMs,
+  validateAgentDiscoveryCacheConfig: () => validateAgentDiscoveryCacheConfig
+});
+module.exports = __toCommonJS(agent_discovery_cache_exports);
+var import_node_crypto = require("node:crypto");
+var import_errors = require('../errors/index.js');
+var import_jcs = require('../utils/jcs.js');
+var import_mcp_call_context = require('../protocols/mcp-call-context.js');
+const DEFAULT_AGENT_DISCOVERY_TTL_MS = 5 * 60 * 1e3;
+const MAX_AGENT_DISCOVERY_TTL_MS = 24 * 60 * 60 * 1e3;
+const DEFAULT_MAX_ENTRIES = 256;
+function createInMemoryAgentDiscoveryCache(options = {}) {
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+    throw new import_errors.ConfigurationError("maxEntries must be a positive safe integer.");
+  }
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      const entry = entries.get(key);
+      if (!entry) return void 0;
+      entries.delete(key);
+      entries.set(key, entry);
+      return structuredClone(entry);
+    },
+    set(key, entry) {
+      entries.delete(key);
+      entries.set(key, structuredClone(entry));
+      while (entries.size > maxEntries) {
+        const oldest = entries.keys().next().value;
+        if (oldest === void 0) break;
+        entries.delete(oldest);
+      }
+    },
+    delete(key) {
+      entries.delete(key);
+    },
+    clear() {
+      entries.clear();
+    },
+    get size() {
+      return entries.size;
+    }
+  };
+}
+function validateAgentDiscoveryCacheConfig(config) {
+  if (config === void 0) return;
+  const cache = config.cache;
+  if (!cache || typeof cache.get !== "function" || typeof cache.set !== "function" || typeof cache.delete !== "function") {
+    throw new import_errors.ConfigurationError("discoveryCache.cache must implement get, set and delete.", "discoveryCache.cache");
+  }
+  if (typeof config.authIdentity !== "string" || config.authIdentity.length === 0) {
+    throw new import_errors.ConfigurationError(
+      "discoveryCache.authIdentity is required: supply a stable caller-owned identity for the principal whose credentials this client uses. It is deliberately not derived from the token, so that two principals can never share discovery evidence by accident.",
+      "discoveryCache.authIdentity"
+    );
+  }
+  resolveAgentDiscoveryTtlMs(config.ttlMs);
+}
+function resolveAgentDiscoveryTtlMs(ttlMs) {
+  if (ttlMs === void 0) return DEFAULT_AGENT_DISCOVERY_TTL_MS;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0 || ttlMs > MAX_AGENT_DISCOVERY_TTL_MS) {
+    throw new import_errors.ConfigurationError(
+      `discoveryCache.ttlMs must be a positive number of milliseconds no greater than ${MAX_AGENT_DISCOVERY_TTL_MS}.`,
+      "discoveryCache.ttlMs"
+    );
+  }
+  return ttlMs;
+}
+function agentDiscoveryCacheKey(input) {
+  const headers = Object.entries((0, import_mcp_call_context.splitConnectionHeaders)(input.headers).identity).map(([name, value]) => [name.toLowerCase(), value]).filter(([name]) => name !== "authorization" && name !== "x-adcp-auth").sort(([left], [right]) => left.localeCompare(right));
+  const digest = (0, import_node_crypto.createHash)("sha256").update(
+    (0, import_jcs.canonicalize)({
+      v: 1,
+      protocol: input.protocol,
+      agentUri: input.agentUri,
+      adcpVersion: input.adcpVersion,
+      wireAdcpVersion: input.wireAdcpVersion ?? null,
+      authIdentity: input.authIdentity,
+      credentialKind: input.credentialKind ?? null,
+      headers,
+      signing: input.signing ?? null,
+      allowPrivateIp: input.allowPrivateIp ?? null,
+      maxResponseBytes: input.maxResponseBytes ?? null
+    })
+  ).digest("hex");
+  return `adcp:agent-discovery:v1:${digest}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_AGENT_DISCOVERY_TTL_MS,
+  MAX_AGENT_DISCOVERY_TTL_MS,
+  agentDiscoveryCacheKey,
+  createInMemoryAgentDiscoveryCache,
+  resolveAgentDiscoveryTtlMs,
+  validateAgentDiscoveryCacheConfig
+});

package/dist/lib/core/agent-discovery-cache.mjs

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { ConfigurationError } from "../errors/index.mjs";
+import { canonicalize as canonicalizeJson } from "../utils/jcs.mjs";
+import { splitConnectionHeaders } from "../protocols/mcp-call-context.mjs";
+const DEFAULT_AGENT_DISCOVERY_TTL_MS = 5 * 60 * 1e3;
+const MAX_AGENT_DISCOVERY_TTL_MS = 24 * 60 * 60 * 1e3;
+const DEFAULT_MAX_ENTRIES = 256;
+function createInMemoryAgentDiscoveryCache(options = {}) {
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+    throw new ConfigurationError("maxEntries must be a positive safe integer.");
+  }
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      const entry = entries.get(key);
+      if (!entry) return void 0;
+      entries.delete(key);
+      entries.set(key, entry);
+      return structuredClone(entry);
+    },
+    set(key, entry) {
+      entries.delete(key);
+      entries.set(key, structuredClone(entry));
+      while (entries.size > maxEntries) {
+        const oldest = entries.keys().next().value;
+        if (oldest === void 0) break;
+        entries.delete(oldest);
+      }
+    },
+    delete(key) {
+      entries.delete(key);
+    },
+    clear() {
+      entries.clear();
+    },
+    get size() {
+      return entries.size;
+    }
+  };
+}
+function validateAgentDiscoveryCacheConfig(config) {
+  if (config === void 0) return;
+  const cache = config.cache;
+  if (!cache || typeof cache.get !== "function" || typeof cache.set !== "function" || typeof cache.delete !== "function") {
+    throw new ConfigurationError("discoveryCache.cache must implement get, set and delete.", "discoveryCache.cache");
+  }
+  if (typeof config.authIdentity !== "string" || config.authIdentity.length === 0) {
+    throw new ConfigurationError(
+      "discoveryCache.authIdentity is required: supply a stable caller-owned identity for the principal whose credentials this client uses. It is deliberately not derived from the token, so that two principals can never share discovery evidence by accident.",
+      "discoveryCache.authIdentity"
+    );
+  }
+  resolveAgentDiscoveryTtlMs(config.ttlMs);
+}
+function resolveAgentDiscoveryTtlMs(ttlMs) {
+  if (ttlMs === void 0) return DEFAULT_AGENT_DISCOVERY_TTL_MS;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0 || ttlMs > MAX_AGENT_DISCOVERY_TTL_MS) {
+    throw new ConfigurationError(
+      `discoveryCache.ttlMs must be a positive number of milliseconds no greater than ${MAX_AGENT_DISCOVERY_TTL_MS}.`,
+      "discoveryCache.ttlMs"
+    );
+  }
+  return ttlMs;
+}
+function agentDiscoveryCacheKey(input) {
+  const headers = Object.entries(splitConnectionHeaders(input.headers).identity).map(([name, value]) => [name.toLowerCase(), value]).filter(([name]) => name !== "authorization" && name !== "x-adcp-auth").sort(([left], [right]) => left.localeCompare(right));
+  const digest = createHash("sha256").update(
+    canonicalizeJson({
+      v: 1,
+      protocol: input.protocol,
+      agentUri: input.agentUri,
+      adcpVersion: input.adcpVersion,
+      wireAdcpVersion: input.wireAdcpVersion ?? null,
+      authIdentity: input.authIdentity,
+      credentialKind: input.credentialKind ?? null,
+      headers,
+      signing: input.signing ?? null,
+      allowPrivateIp: input.allowPrivateIp ?? null,
+      maxResponseBytes: input.maxResponseBytes ?? null
+    })
+  ).digest("hex");
+  return `adcp:agent-discovery:v1:${digest}`;
+}
+export {
+  DEFAULT_AGENT_DISCOVERY_TTL_MS,
+  MAX_AGENT_DISCOVERY_TTL_MS,
+  agentDiscoveryCacheKey,
+  createInMemoryAgentDiscoveryCache,
+  resolveAgentDiscoveryTtlMs,
+  validateAgentDiscoveryCacheConfig
+};

package/dist/lib/index.d.mts

@@ -14,7 +14,9 @@ export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFe
 export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from './discovery/agent-directory.mjs';
 export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from './discovery/validate-adagents.mjs';
 export { SingleAgentClient, WebhookDispatchError, createSingleAgentClient, UnsupportedFeatureError, } from './core/SingleAgentClient.mjs';
-export type { CapabilityEvidenceScope, CapabilityEvidenceSnapshot, ClientProductPropertyPolicy, CreativeDeliveryTaskOptions, SingleAgentClientConfig, StatusHandlerErrorContext, SyncCreativesTaskOptions, VerifyAndParseWebhookOptions, WebhookHandlerAdapter, WebhookHandlerRequest, WebhookRequestContext, WebhookParseErrorCode, WebhookParseFailure, WebhookParseResult, WebhookParseSuccess, WebhookVerificationConfig, } from './core/SingleAgentClient.mjs';
+export { createInMemoryAgentDiscoveryCache } from './core/agent-discovery-cache.mjs';
+export type { AgentDiscoveryCache, AgentDiscoveryCacheConfig, AgentDiscoveryEntry, InMemoryAgentDiscoveryCache, InMemoryAgentDiscoveryCacheOptions, } from './core/agent-discovery-cache.mjs';
+export type { AgentDiscoverySeed, CapabilityEvidenceScope, CapabilityEvidenceSnapshot, ClientProductPropertyPolicy, CreativeDeliveryTaskOptions, SingleAgentClientConfig, StatusHandlerErrorContext, SyncCreativesTaskOptions, VerifyAndParseWebhookOptions, WebhookHandlerAdapter, WebhookHandlerRequest, WebhookRequestContext, WebhookParseErrorCode, WebhookParseFailure, WebhookParseResult, WebhookParseSuccess, WebhookVerificationConfig, } from './core/SingleAgentClient.mjs';
 export { InMemoryWebhookRegistrationStore, type InMemoryWebhookRegistrationStoreOptions, type WebhookAuthenticationMode, type WebhookRegistration, type WebhookRegistrationStore, } from './core/webhook-registration.mjs';
 export { pgWebhookRegistrationStore, getWebhookRegistrationMigration, WEBHOOK_REGISTRATION_MIGRATION, cleanupExpiredWebhookRegistrations, type PgWebhookRegistrationStoreOptions, type CleanupExpiredWebhookRegistrationsOptions, } from './core/postgres-webhook-registration-store.mjs';
 export { redisWebhookRegistrationStore, type RedisWebhookRegistrationStoreOptions, } from './core/redis-webhook-registration-store.mjs';
@@ -188,9 +190,9 @@ export { runAuthDiagnosis, AUTH_DIAGNOSIS_SCHEMA_VERSION, type DiagnoseOptions,
 export { NeedsAuthorizationError, discoverAuthorizationRequirements, hasValidatedMcpAuthorizationRequirements, createFileOAuthStorage, bindAgentStorage, getAgentStorage, unbindAgentStorage, type AuthorizationRequirements, type DiscoverAuthorizationOptions, type FileOAuthStorageOptions, } from './auth/oauth/index.mjs';
 export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, MissingEnvSecretError, resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, type AgentOAuthClientCredentials, AgentOAuthClientCredentialsSchema, } from './auth/oauth/index.mjs';
 export { validateAgentUrl, validateAdCPResponse, getExpectedSchema, handleAdCPResponse } from './validation/index.mjs';
-export { ProtocolClient, callMCPTool, callA2ATool, createA2AClientFromCardUrl, createMCPClient, createA2AClient, closeMCPConnections, closeOAuthConnections, bundleSupportsAdcpVersionField, BODY_SNIPPET_TIMEOUT_MS, OBSERVER_FLUSH_TIMEOUT_MS, sanitizeTransportHeaders, sanitizeTransportUrl, } from './protocols/index.mjs';
+export { ProtocolClient, callMCPTool, callA2ATool, createA2AClientFromCardUrl, createMCPClient, createA2AClient, closeMCPConnections, closeOAuthConnections, closeScopedConnections, withMCPConnectionScope, bundleSupportsAdcpVersionField, BODY_SNIPPET_TIMEOUT_MS, OBSERVER_FLUSH_TIMEOUT_MS, sanitizeTransportHeaders, sanitizeTransportUrl, } from './protocols/index.mjs';
 export { toReleasePrecisionWire, validateAdcpVersionWire } from './validation/schema-loader.mjs';
-export type { CallToolOptions, TransportActivity, TransportActivityContext, TransportActivityHandler, TransportOptions, A2ALegacyCompatOptions, } from './protocols/index.mjs';
+export type { CallToolOptions, TransportActivity, TransportActivityContext, TransportActivityHandler, TransportActivityType, TransportResponseOutcome, TransportOptions, A2ALegacyCompatOptions, } from './protocols/index.mjs';
 import { bundleSupportsAdcpVersionField as _isSupported } from './protocols/index.mjs';
 import { toReleasePrecisionWire as _normalize, validateAdcpVersionWire as _validate } from './validation/schema-loader.mjs';
 export declare const wireVersion: {

package/dist/lib/index.d.ts

@@ -14,7 +14,9 @@ export { resolveInlinePublisherProperties, resolveSingularInline, detectInlineFe
 export { fetchAgentAuthorizationsFromDirectory, type AgentAuthorizationsIterator, type FetchAgentAuthorizationsOptions, type DirectoryLookupPage, type DirectoryPublisherEntry, type DirectoryDiscoveryMethod, type DirectoryPublisherStatus, } from './discovery/agent-directory';
 export { validateAdAgents, parseManagerDomain, type DiscoveryMethod, type AdAgentsValidationResult, type ValidateAdAgentsOptions, } from './discovery/validate-adagents';
 export { SingleAgentClient, WebhookDispatchError, createSingleAgentClient, UnsupportedFeatureError, } from './core/SingleAgentClient';
-export type { CapabilityEvidenceScope, CapabilityEvidenceSnapshot, ClientProductPropertyPolicy, CreativeDeliveryTaskOptions, SingleAgentClientConfig, StatusHandlerErrorContext, SyncCreativesTaskOptions, VerifyAndParseWebhookOptions, WebhookHandlerAdapter, WebhookHandlerRequest, WebhookRequestContext, WebhookParseErrorCode, WebhookParseFailure, WebhookParseResult, WebhookParseSuccess, WebhookVerificationConfig, } from './core/SingleAgentClient';
+export { createInMemoryAgentDiscoveryCache } from './core/agent-discovery-cache';
+export type { AgentDiscoveryCache, AgentDiscoveryCacheConfig, AgentDiscoveryEntry, InMemoryAgentDiscoveryCache, InMemoryAgentDiscoveryCacheOptions, } from './core/agent-discovery-cache';
+export type { AgentDiscoverySeed, CapabilityEvidenceScope, CapabilityEvidenceSnapshot, ClientProductPropertyPolicy, CreativeDeliveryTaskOptions, SingleAgentClientConfig, StatusHandlerErrorContext, SyncCreativesTaskOptions, VerifyAndParseWebhookOptions, WebhookHandlerAdapter, WebhookHandlerRequest, WebhookRequestContext, WebhookParseErrorCode, WebhookParseFailure, WebhookParseResult, WebhookParseSuccess, WebhookVerificationConfig, } from './core/SingleAgentClient';
 export { InMemoryWebhookRegistrationStore, type InMemoryWebhookRegistrationStoreOptions, type WebhookAuthenticationMode, type WebhookRegistration, type WebhookRegistrationStore, } from './core/webhook-registration';
 export { pgWebhookRegistrationStore, getWebhookRegistrationMigration, WEBHOOK_REGISTRATION_MIGRATION, cleanupExpiredWebhookRegistrations, type PgWebhookRegistrationStoreOptions, type CleanupExpiredWebhookRegistrationsOptions, } from './core/postgres-webhook-registration-store';
 export { redisWebhookRegistrationStore, type RedisWebhookRegistrationStoreOptions, } from './core/redis-webhook-registration-store';
@@ -188,9 +190,9 @@ export { runAuthDiagnosis, AUTH_DIAGNOSIS_SCHEMA_VERSION, type DiagnoseOptions,
 export { NeedsAuthorizationError, discoverAuthorizationRequirements, hasValidatedMcpAuthorizationRequirements, createFileOAuthStorage, bindAgentStorage, getAgentStorage, unbindAgentStorage, type AuthorizationRequirements, type DiscoverAuthorizationOptions, type FileOAuthStorageOptions, } from './auth/oauth';
 export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, MissingEnvSecretError, resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, type AgentOAuthClientCredentials, AgentOAuthClientCredentialsSchema, } from './auth/oauth';
 export { validateAgentUrl, validateAdCPResponse, getExpectedSchema, handleAdCPResponse } from './validation';
-export { ProtocolClient, callMCPTool, callA2ATool, createA2AClientFromCardUrl, createMCPClient, createA2AClient, closeMCPConnections, closeOAuthConnections, bundleSupportsAdcpVersionField, BODY_SNIPPET_TIMEOUT_MS, OBSERVER_FLUSH_TIMEOUT_MS, sanitizeTransportHeaders, sanitizeTransportUrl, } from './protocols';
+export { ProtocolClient, callMCPTool, callA2ATool, createA2AClientFromCardUrl, createMCPClient, createA2AClient, closeMCPConnections, closeOAuthConnections, closeScopedConnections, withMCPConnectionScope, bundleSupportsAdcpVersionField, BODY_SNIPPET_TIMEOUT_MS, OBSERVER_FLUSH_TIMEOUT_MS, sanitizeTransportHeaders, sanitizeTransportUrl, } from './protocols';
 export { toReleasePrecisionWire, validateAdcpVersionWire } from './validation/schema-loader';
-export type { CallToolOptions, TransportActivity, TransportActivityContext, TransportActivityHandler, TransportOptions, A2ALegacyCompatOptions, } from './protocols';
+export type { CallToolOptions, TransportActivity, TransportActivityContext, TransportActivityHandler, TransportActivityType, TransportResponseOutcome, TransportOptions, A2ALegacyCompatOptions, } from './protocols';
 import { bundleSupportsAdcpVersionField as _isSupported } from './protocols';
 import { toReleasePrecisionWire as _normalize, validateAdcpVersionWire as _validate } from './validation/schema-loader';
 export declare const wireVersion: {

package/dist/lib/index.js

@@ -296,6 +296,7 @@ __export(index_exports, {
   clearPreviewCache: () => import_utils4.clearPreviewCache,
   closeMCPConnections: () => import_protocols.closeMCPConnections,
   closeOAuthConnections: () => import_protocols.closeOAuthConnections,
+  closeScopedConnections: () => import_protocols.closeScopedConnections,
   compileUniversalMacroTemplate: () => import_substitution.compileUniversalMacroTemplate,
   computeGovernedPayloadHash: () => import_governance.computeGovernedPayloadHash,
   createA2AAdapter: () => import_server.createA2AAdapter,
@@ -316,6 +317,7 @@ __export(index_exports, {
   createGovernanceAgentJwksResolver: () => import_governance.createGovernanceAgentJwksResolver,
   createGovernanceEnforcementMiddleware: () => import_governance.createGovernanceEnforcementMiddleware,
   createIdempotencyStore: () => import_server.createIdempotencyStore,
+  createInMemoryAgentDiscoveryCache: () => import_agent_discovery_cache.createInMemoryAgentDiscoveryCache,
   createInMemoryEstablishedProposalStore: () => import_established_proposal_store.createInMemoryEstablishedProposalStore,
   createInMemoryLegacyPurchaseContinuationStore: () => import_legacy_purchase_continuation.createInMemoryLegacyPurchaseContinuationStore,
   createLazyBackend: () => import_server.createLazyBackend,
@@ -724,6 +726,7 @@ __export(index_exports, {
   windowUpdateMediaBuyDeliveryNotification: () => import_media_buy_delivery_notification_builders.windowUpdateMediaBuyDeliveryNotification,
   wireVersion: () => wireVersion,
   withAdditiveCanonicalFormatOptions: () => import_projection2.withAdditiveCanonicalFormatOptions,
+  withMCPConnectionScope: () => import_protocols.withMCPConnectionScope,
   withSpan: () => import_observability.withSpan
 });
 module.exports = __toCommonJS(index_exports);
@@ -739,6 +742,7 @@ var import_inline_publisher_properties = require('./discovery/inline-publisher-p
 var import_agent_directory = require('./discovery/agent-directory.js');
 var import_validate_adagents = require('./discovery/validate-adagents.js');
 var import_SingleAgentClient = require('./core/SingleAgentClient.js');
+var import_agent_discovery_cache = require('./core/agent-discovery-cache.js');
 var import_webhook_registration = require('./core/webhook-registration.js');
 var import_postgres_webhook_registration_store = require('./core/postgres-webhook-registration-store.js');
 var import_redis_webhook_registration_store = require('./core/redis-webhook-registration-store.js');
@@ -1137,6 +1141,7 @@ function createAdCPClientFromEnv() {
   clearPreviewCache,
   closeMCPConnections,
   closeOAuthConnections,
+  closeScopedConnections,
   compileUniversalMacroTemplate,
   computeGovernedPayloadHash,
   createA2AAdapter,
@@ -1157,6 +1162,7 @@ function createAdCPClientFromEnv() {
   createGovernanceAgentJwksResolver,
   createGovernanceEnforcementMiddleware,
   createIdempotencyStore,
+  createInMemoryAgentDiscoveryCache,
   createInMemoryEstablishedProposalStore,
   createInMemoryLegacyPurchaseContinuationStore,
   createLazyBackend,
@@ -1565,6 +1571,7 @@ function createAdCPClientFromEnv() {
   windowUpdateMediaBuyDeliveryNotification,
   wireVersion,
   withAdditiveCanonicalFormatOptions,
+  withMCPConnectionScope,
   withSpan,
   ...require('./principal/index.js'),
   ...require('./handlers/types.js'),

package/dist/lib/index.mjs

@@ -75,6 +75,7 @@ import {
   createSingleAgentClient,
   UnsupportedFeatureError
 } from "./core/SingleAgentClient.mjs";
+import { createInMemoryAgentDiscoveryCache } from "./core/agent-discovery-cache.mjs";
 import {
   InMemoryWebhookRegistrationStore
 } from "./core/webhook-registration.mjs";
@@ -458,6 +459,8 @@ import {
   createA2AClient,
   closeMCPConnections,
   closeOAuthConnections,
+  closeScopedConnections,
+  withMCPConnectionScope,
   bundleSupportsAdcpVersionField,
   BODY_SNIPPET_TIMEOUT_MS,
   OBSERVER_FLUSH_TIMEOUT_MS,
@@ -1096,6 +1099,7 @@ export {
   clearPreviewCache,
   closeMCPConnections,
   closeOAuthConnections,
+  closeScopedConnections,
   compileUniversalMacroTemplate,
   computeGovernedPayloadHash,
   createA2AAdapter,
@@ -1116,6 +1120,7 @@ export {
   createGovernanceAgentJwksResolver,
   createGovernanceEnforcementMiddleware,
   createIdempotencyStore,
+  createInMemoryAgentDiscoveryCache,
   createInMemoryEstablishedProposalStore,
   createInMemoryLegacyPurchaseContinuationStore,
   createLazyBackend,
@@ -1524,5 +1529,6 @@ export {
   windowUpdateMediaBuyDeliveryNotification,
   wireVersion,
   withAdditiveCanonicalFormatOptions,
+  withMCPConnectionScope,
   withSpan
 };

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

@@ -5,7 +5,7 @@ import { withMCPConnectionScope } from './mcp-scope.mjs';
  * MCP closes persistent HTTP transports; A2A clears the agent-card client cache.
  */
 export declare function closeConnections(protocol?: 'mcp' | 'a2a'): Promise<void>;
-/** Close only the current runner's MCP scope; fall back to legacy global cleanup. */
+/** Close the current MCP scope. Without an active MCP scope, leave other callers' sessions open. */
 export declare function closeScopedConnections(protocol?: 'mcp' | 'a2a'): Promise<void>;
 export { withMCPConnectionScope };
 export type { MCPCallOptions, MCPConnectionResult } from './mcp.mjs';
@@ -16,7 +16,7 @@ import type { AgentConfig, DebugLogEntry } from '../types/index.mjs';
 import type { PushNotificationConfig } from '../types/tools.generated.mjs';
 import { type TransportActivityHandler as TransportActivityHandlerFn } from './transportDiagnostics.mjs';
 export { BODY_SNIPPET_TIMEOUT_MS, OBSERVER_FLUSH_TIMEOUT_MS, sanitizeTransportHeaders, sanitizeTransportUrl, withTransportDiagnostics, wrapFetchWithTransportDiagnostics, } from './transportDiagnostics.mjs';
-export type { TransportActivity, TransportActivityContext, TransportActivityHandler } from './transportDiagnostics.mjs';
+export type { TransportActivity, TransportActivityContext, TransportActivityHandler, TransportActivityType, TransportResponseOutcome, } from './transportDiagnostics.mjs';
 export type VersionEnvelopeMode = 'auto' | 'none' | 'major-only';
 /**
  * Returns true when the AdCP release that `bundleKey` identifies declares the

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

@@ -5,7 +5,7 @@ import { withMCPConnectionScope } from './mcp-scope';
  * MCP closes persistent HTTP transports; A2A clears the agent-card client cache.
  */
 export declare function closeConnections(protocol?: 'mcp' | 'a2a'): Promise<void>;
-/** Close only the current runner's MCP scope; fall back to legacy global cleanup. */
+/** Close the current MCP scope. Without an active MCP scope, leave other callers' sessions open. */
 export declare function closeScopedConnections(protocol?: 'mcp' | 'a2a'): Promise<void>;
 export { withMCPConnectionScope };
 export type { MCPCallOptions, MCPConnectionResult } from './mcp';
@@ -16,7 +16,7 @@ import type { AgentConfig, DebugLogEntry } from '../types';
 import type { PushNotificationConfig } from '../types/tools.generated';
 import { type TransportActivityHandler as TransportActivityHandlerFn } from './transportDiagnostics';
 export { BODY_SNIPPET_TIMEOUT_MS, OBSERVER_FLUSH_TIMEOUT_MS, sanitizeTransportHeaders, sanitizeTransportUrl, withTransportDiagnostics, wrapFetchWithTransportDiagnostics, } from './transportDiagnostics';
-export type { TransportActivity, TransportActivityContext, TransportActivityHandler } from './transportDiagnostics';
+export type { TransportActivity, TransportActivityContext, TransportActivityHandler, TransportActivityType, TransportResponseOutcome, } from './transportDiagnostics';
 export type VersionEnvelopeMode = 'auto' | 'none' | 'major-only';
 /**
  * Returns true when the AdCP release that `bundleKey` identifies declares the

package/dist/lib/protocols/index.js

@@ -90,7 +90,7 @@ async function closeConnections(protocol = "mcp") {
 }
 async function closeScopedConnections(protocol = "mcp") {
   if (protocol === "mcp") {
-    if (!await (0, import_mcp_scope.closeCurrentMCPConnectionScope)()) await (0, import_mcp2.closeMCPConnections)();
+    await (0, import_mcp_scope.closeCurrentMCPConnectionScope)();
   } else {
     (0, import_a2a.closeA2AConnections)();
   }

package/dist/lib/protocols/index.mjs

@@ -24,7 +24,7 @@ async function closeConnections(protocol = "mcp") {
 }
 async function closeScopedConnections(protocol = "mcp") {
   if (protocol === "mcp") {
-    if (!await closeCurrentMCPConnectionScope()) await closeMCPConnections2();
+    await closeCurrentMCPConnectionScope();
   } else {
     closeA2AConnections();
   }