@adcp/sdk 9.3.0 → 9.5.0

package/dist/lib/core/SingleAgentClient.js

@@ -46,6 +46,7 @@ const idempotency_1 = require("../utils/idempotency");
 const TaskExecutor_1 = require("./TaskExecutor");
 const match_1 = require("./match");
 const auth_1 = require("../auth");
+const abort_1 = require("../protocols/abort");
 const errors_1 = require("../errors");
 const net_1 = require("../net");
 const authorization_required_1 = require("../auth/oauth/authorization-required");
@@ -55,6 +56,7 @@ const webhooks_1 = require("../webhooks");
 const response_unwrapper_1 = require("../utils/response-unwrapper");
 const a2a_discovery_1 = require("../utils/a2a-discovery");
 const crypto = __importStar(require("crypto"));
+const abort_2 = require("../protocols/abort");
 const capabilities_1 = require("../utils/capabilities");
 const request_normalizer_1 = require("../utils/request-normalizer");
 const validate_user_agent_1 = require("../utils/validate-user-agent");
@@ -313,7 +315,8 @@ class SingleAgentClient {
      * Returns the agent config with the discovered endpoint.
      * Also computes the canonical base URL by stripping /mcp suffix.
      */
-    async ensureEndpointDiscovered() {
+    async ensureEndpointDiscovered(options) {
+        (0, abort_2.throwIfAborted)(options?.signal);
         const needsDiscovery = this.normalizedAgent._needsDiscovery;
         if (!needsDiscovery) {
             return this.normalizedAgent;
@@ -330,7 +333,7 @@ class SingleAgentClient {
             return this.discoveredAgent;
         }
         // Perform discovery
-        this.discoveredEndpoint = await this.discoverMCPEndpoint(this.normalizedAgent.agent_uri);
+        this.discoveredEndpoint = await this.discoverMCPEndpoint(this.normalizedAgent.agent_uri, options);
         // Compute canonical base URL by stripping /mcp suffix
         this.canonicalBaseUrl = this.computeBaseUrl(this.discoveredEndpoint);
         this.discoveredAgent = {
@@ -345,7 +348,8 @@ class SingleAgentClient {
      * Fetches the agent card and extracts the canonical URL.
      * Returns the agent config with the canonical URL.
      */
-    async ensureCanonicalUrlResolved() {
+    async ensureCanonicalUrlResolved(options) {
+        (0, abort_2.throwIfAborted)(options?.signal);
         const needsCanonicalUrl = this.normalizedAgent._needsCanonicalUrl;
         if (!needsCanonicalUrl) {
             return this.normalizedAgent;
@@ -358,7 +362,7 @@ class SingleAgentClient {
             };
         }
         // Fetch agent card to get canonical URL
-        const canonicalUrl = await this.fetchA2ACanonicalUrl(this.normalizedAgent.agent_uri);
+        const canonicalUrl = await this.fetchA2ACanonicalUrl(this.normalizedAgent.agent_uri, options);
         this.canonicalBaseUrl = canonicalUrl;
         return {
             ...this.normalizedAgent,
@@ -372,7 +376,7 @@ class SingleAgentClient {
      * - If the agent card fetch returns 401, throw AuthenticationRequiredError
      * - Check for OAuth metadata to provide helpful guidance
      */
-    async fetchA2ACanonicalUrl(agentUri) {
+    async fetchA2ACanonicalUrl(agentUri, readOptions) {
         const clientModule = require('@a2a-js/sdk/client');
         const A2AClient = clientModule.A2AClient;
         // adcp-client#1804 — wrap A2A card discovery in withResponseSizeLimit so
@@ -381,20 +385,22 @@ class SingleAgentClient {
         // active ALS slot enforces the cap on the wire call. Matches the same
         // pattern in `getAgentInfo` (closed #1799 via PR #1802).
         const { withResponseSizeLimit, wrapFetchWithSizeLimit } = await Promise.resolve().then(() => __importStar(require('../protocols/responseSizeLimit')));
-        const maxResponseBytes = this.config.transport?.maxResponseBytes;
+        const transport = readOptions?.transport ?? this.config.transport;
+        const maxResponseBytes = transport?.maxResponseBytes;
+        const requestTimeoutMs = (0, abort_2.resolveRequestTimeoutMs)(transport?.requestTimeoutMs, abort_2.DEFAULT_REQUEST_TIMEOUT_MS);
         const sizeLimitedFetch = wrapFetchWithSizeLimit((input, init) => fetch(input, init));
         const authToken = this.normalizedAgent.auth_token;
         let got401 = false;
-        const fetchImpl = async (url, options) => {
+        const fetchImpl = async (url, requestInit) => {
             const headers = {
-                ...options?.headers,
+                ...requestInit?.headers,
                 ...this.normalizedAgent.headers,
                 ...(authToken && {
                     Authorization: `Bearer ${authToken}`,
                     'x-adcp-auth': authToken,
                 }),
             };
-            const response = await sizeLimitedFetch(url, { ...options, headers });
+            const response = await (0, abort_2.withAbortSignal)([readOptions?.signal, requestInit?.signal], requestTimeoutMs, signal => sizeLimitedFetch(url, { ...requestInit, headers, signal }));
             // Track 401 errors for later handling
             if (response.status === 401) {
                 got401 = true;
@@ -481,18 +487,25 @@ class SingleAgentClient {
      *
      * Note: This is async and called lazily on first agent interaction
      */
-    async discoverMCPEndpoint(providedUri) {
+    async discoverMCPEndpoint(providedUri, options) {
+        (0, abort_2.throwIfAborted)(options?.signal);
         const { connectMCPWithFallback } = await Promise.resolve().then(() => __importStar(require('../protocols/mcp')));
         const authToken = this.agent.auth_token;
         const agentHeaders = this.agent.headers;
         const authHeaders = { ...agentHeaders, ...(0, auth_1.createMCPAuthHeaders)(authToken) };
         const testEndpoint = async (url) => {
             try {
-                const client = await connectMCPWithFallback(new URL(url), authHeaders);
+                const client = await connectMCPWithFallback(new URL(url), authHeaders, [], 'endpoint discovery', undefined, {
+                    signal: options?.signal,
+                    requestTimeoutMs: options?.transport?.requestTimeoutMs ?? this.config.transport?.requestTimeoutMs,
+                });
                 await client.close();
                 return { success: true };
             }
             catch (error) {
+                if ((0, abort_1.isAbortOrTimeoutError)(error)) {
+                    throw error;
+                }
                 if ((0, errors_1.is401Error)(error)) {
                     return { success: false, status: 401, error };
                 }
@@ -1041,6 +1054,7 @@ class SingleAgentClient {
      * Automatically adapts requests for v2 servers and normalizes responses.
      */
     async executeAndHandle(taskType, handlerName, params, inputHandler, options) {
+        (0, abort_2.throwIfAborted)(options?.signal);
         // Normalize params for backwards compatibility before validation
         let normalizedParams = (0, request_normalizer_1.normalizeRequestParams)(taskType, params, {
             skipIdempotencyAutoInject: options?.skipIdempotencyAutoInject,
@@ -1075,17 +1089,17 @@ class SingleAgentClient {
             this.validateRequest(taskType, normalizedParams);
         }
         // Validate required features before sending request
-        await this.validateTaskFeatures(taskType);
+        await this.validateTaskFeatures(taskType, options);
         // Guard mutating calls against pre-v3 sellers when opted in.
         if (this.config.requireV3ForMutations && (0, idempotency_1.isMutatingTask)(taskType)) {
-            await this.requireSupportedMajor(taskType);
+            await this.requireSupportedMajor(taskType, options);
         }
         // Check for v3 features used against v2 servers - return empty result if unsupported
-        const earlyResult = await this.getEarlyResultForUnsupportedFeatures(taskType, normalizedParams);
+        const earlyResult = await this.getEarlyResultForUnsupportedFeatures(taskType, normalizedParams, options);
         if (earlyResult) {
             return (0, match_1.attachMatch)(earlyResult);
         }
-        const agent = await this.ensureEndpointDiscovered();
+        const agent = await this.ensureEndpointDiscovered(options);
         // Schema-driven pre-send validation runs on the unadapted v3 shape so
         // wire-format adapters (e.g. adaptGetProductsRequestForV2) don't strip
         // v3-only fields out from under the v3 bundled schema. Skip the entire
@@ -1095,7 +1109,7 @@ class SingleAgentClient {
             this.executor.validateRequest(taskType, normalizedParams);
         }
         // Adapt request for the detected server and AdCP protocol versions.
-        const serverVersion = await this.detectServerVersion();
+        const serverVersion = await this.detectServerVersion(options);
         const inputSchemaStripLogs = [];
         const { params: adaptedParams, driftLogs: adaptDriftLogs } = this.adaptRequest(taskType, normalizedParams, serverVersion, inputSchemaStripLogs);
         // Symmetric to the pre-adapter v3 pass above: when the adapter
@@ -1584,13 +1598,13 @@ class SingleAgentClient {
      *
      * @returns TaskResult with empty data if v3 features are unsupported, null to proceed normally
      */
-    async getEarlyResultForUnsupportedFeatures(taskType, params) {
+    async getEarlyResultForUnsupportedFeatures(taskType, params, options) {
         // Only check for tasks that have v3-specific features
         if (taskType !== 'get_products') {
             return null;
         }
         // Get capabilities to check what the server supports
-        const capabilities = await this.getCapabilities();
+        const capabilities = await this.getCapabilities(options);
         // If server is v3, all features are supported - proceed normally
         if (capabilities.version === 'v3') {
             return null;
@@ -1867,7 +1881,7 @@ class SingleAgentClient {
      * @param options - Task execution options
      */
     async getAdcpCapabilities(params, inputHandler, options) {
-        const agent = await this.ensureEndpointDiscovered();
+        const agent = await this.ensureEndpointDiscovered(options);
         this.executor.validateRequest('get_adcp_capabilities', params);
         return this.executor.executeTask(agent, 'get_adcp_capabilities', params, inputHandler, options);
     }
@@ -1996,6 +2010,7 @@ class SingleAgentClient {
      * ```
      */
     async executeTask(taskName, params, inputHandler, options) {
+        (0, abort_2.throwIfAborted)(options?.signal);
         const startTime = Date.now();
         try {
             const normalizedParams = (0, request_normalizer_1.normalizeRequestParams)(taskName, params, {
@@ -2007,11 +2022,11 @@ class SingleAgentClient {
             // (get_products / get_signals). `effectiveOptions` carries disableWebhook
             // so no push_notification_config reaches a seller that can't accept it.
             const { options: effectiveOptions, driftLog: webhookDriftLog } = this.suppressPre31DiscoveryWebhook(taskName, options);
-            await this.validateTaskFeatures(taskName);
+            await this.validateTaskFeatures(taskName, options);
             if (this.config.requireV3ForMutations && (0, idempotency_1.isMutatingTask)(taskName)) {
-                await this.requireSupportedMajor(taskName);
+                await this.requireSupportedMajor(taskName, options);
             }
-            const agent = await this.ensureEndpointDiscovered();
+            const agent = await this.ensureEndpointDiscovered(options);
             // Schema-driven pre-send validation runs on the unadapted v3 shape so
             // wire-format adapters (e.g. adaptGetProductsRequestForV2) don't strip
             // v3-only fields out from under the v3 bundled schema. Skip the entire
@@ -2021,7 +2036,7 @@ class SingleAgentClient {
                 this.executor.validateRequest(taskName, normalizedParams);
             }
             // Adapt request for the detected server and AdCP protocol versions.
-            const serverVersion = await this.detectServerVersion();
+            const serverVersion = await this.detectServerVersion(options);
             const inputSchemaStripLogs = [];
             const { params: adaptedParams, driftLogs: adaptDriftLogs } = this.adaptRequest(taskName, normalizedParams, serverVersion, inputSchemaStripLogs);
             // Symmetric warn-only post-adapter pass against the v2.5 schema bundle.
@@ -2055,7 +2070,8 @@ class SingleAgentClient {
             if (error instanceof errors_1.AuthenticationRequiredError ||
                 error instanceof errors_1.TaskTimeoutError ||
                 error instanceof errors_1.VersionUnsupportedError ||
-                error instanceof errors_1.FeatureUnsupportedError) {
+                error instanceof errors_1.FeatureUnsupportedError ||
+                (0, abort_1.isAbortOrTimeoutError)(error)) {
                 throw error;
             }
             // Unexpected pre-flight errors (e.g. a TypeError from response parsing
@@ -2408,17 +2424,25 @@ class SingleAgentClient {
      * });
      * ```
      */
-    async getAgentInfo() {
+    async getAgentInfo(options) {
         // adcp-client#1799 — wrap every wire call in the response-size cap so
         // `transport.maxResponseBytes` extends to discovery / tools-list bodies.
         // `withResponseSizeLimit` is a no-op when no cap is configured.
         const { withResponseSizeLimit } = await Promise.resolve().then(() => __importStar(require('../protocols/responseSizeLimit')));
-        const maxResponseBytes = this.config.transport?.maxResponseBytes;
+        (0, abort_2.throwIfAborted)(options?.signal);
+        const transport = options?.transport ?? this.config.transport;
+        const maxResponseBytes = transport?.maxResponseBytes;
+        const requestTimeoutMs = (0, abort_2.resolveRequestTimeoutMs)(transport?.requestTimeoutMs, abort_2.DEFAULT_REQUEST_TIMEOUT_MS);
+        const clientRequestTimeoutMs = (0, abort_2.resolveClientRequestTimeoutMs)(transport?.requestTimeoutMs);
+        const mcpRequestOptions = {
+            ...(options?.signal && { signal: options.signal }),
+            ...(clientRequestTimeoutMs !== undefined && { timeout: clientRequestTimeoutMs }),
+        };
         if (this.normalizedAgent.protocol === 'mcp') {
             // In-process: use the pre-connected client instead of opening a new HTTP connection
             if (this.normalizedAgent._inProcessMcpClient) {
                 const mcpClient = this.normalizedAgent._inProcessMcpClient;
-                const toolsList = await withResponseSizeLimit(maxResponseBytes, () => mcpClient.listTools());
+                const toolsList = await withResponseSizeLimit(maxResponseBytes, () => mcpClient.listTools(undefined, mcpRequestOptions));
                 const tools = toolsList.tools.map(tool => ({
                     name: tool.name,
                     description: tool.description,
@@ -2434,7 +2458,7 @@ class SingleAgentClient {
                 };
             }
             // Discover endpoint if needed
-            const agent = await this.ensureEndpointDiscovered();
+            const agent = await this.ensureEndpointDiscovered(options);
             // Use the shared connectMCP path so both static bearer AND saved OAuth
             // tokens work. OAuth takes the refresh-capable authProvider branch.
             // Header-only auth (basic, x-api-key, custom routing) lives on
@@ -2443,6 +2467,12 @@ class SingleAgentClient {
             // SDK doesn't emit a competing `Authorization: Bearer …`.
             const { connectMCP } = await Promise.resolve().then(() => __importStar(require('../protocols/mcp')));
             const connectOptions = { agentUrl: agent.agent_uri };
+            if (options?.signal) {
+                connectOptions.signal = options.signal;
+            }
+            if (transport?.requestTimeoutMs !== undefined) {
+                connectOptions.requestTimeoutMs = transport.requestTimeoutMs;
+            }
             if (this.normalizedAgent.headers && Object.keys(this.normalizedAgent.headers).length > 0) {
                 connectOptions.customHeaders = this.normalizedAgent.headers;
             }
@@ -2457,7 +2487,7 @@ class SingleAgentClient {
             }
             const { client: mcpClient } = await connectMCP(connectOptions);
             try {
-                const toolsList = await withResponseSizeLimit(maxResponseBytes, () => mcpClient.listTools());
+                const toolsList = await withResponseSizeLimit(maxResponseBytes, () => mcpClient.listTools(undefined, mcpRequestOptions));
                 const tools = toolsList.tools.map(tool => ({
                     name: tool.name,
                     description: tool.description,
@@ -2491,17 +2521,39 @@ class SingleAgentClient {
             // calls native `fetch` directly and ignores `transport.maxResponseBytes`.
             const { wrapFetchWithSizeLimit } = await Promise.resolve().then(() => __importStar(require('../protocols/responseSizeLimit')));
             const authToken = this.normalizedAgent.auth_token;
+            const agentHeaders = this.normalizedAgent.headers ?? {};
             const sizeLimitedFetch = wrapFetchWithSizeLimit((input, init) => fetch(input, init));
-            const fetchImpl = authToken
-                ? async (url, options) => {
-                    const headers = {
-                        ...options?.headers,
-                        Authorization: `Bearer ${authToken}`,
-                        'x-adcp-auth': authToken,
-                    };
-                    return sizeLimitedFetch(url, { ...options, headers });
+            const normalizeHeaders = (headers) => {
+                const normalized = {};
+                if (!headers)
+                    return normalized;
+                if (headers instanceof Headers) {
+                    headers.forEach((value, key) => {
+                        normalized[key] = value;
+                    });
+                }
+                else if (Array.isArray(headers)) {
+                    for (const [key, value] of headers) {
+                        normalized[key] = value;
+                    }
+                }
+                else {
+                    Object.assign(normalized, headers);
                 }
-                : (url, options) => sizeLimitedFetch(url, options);
+                return normalized;
+            };
+            const buildHeaders = (requestInit) => ({
+                ...normalizeHeaders(requestInit?.headers),
+                ...agentHeaders,
+                ...(authToken && {
+                    Authorization: `Bearer ${authToken}`,
+                    'x-adcp-auth': authToken,
+                }),
+            });
+            const fetchImpl = async (url, requestInit) => {
+                const headers = buildHeaders(requestInit);
+                return (0, abort_2.withAbortSignal)([options?.signal, requestInit?.signal], requestTimeoutMs, signal => sizeLimitedFetch(url, { ...requestInit, headers, signal }));
+            };
             const cardUrls = (0, a2a_discovery_1.buildCardUrls)(this.normalizedAgent.agent_uri);
             let client;
             let lastCardError = new Error(`A2A agent card not found at ${cardUrls.join(', ')}`);
@@ -2559,14 +2611,15 @@ class SingleAgentClient {
      * }
      * ```
      */
-    async getCapabilities() {
+    async getCapabilities(options) {
+        (0, abort_2.throwIfAborted)(options?.signal);
         // Return cached if available
         if (this.cachedCapabilities) {
             this.maybeWarnV2Sunset(this.cachedCapabilities);
             return this.cachedCapabilities;
         }
         // First get tool list to support both detection methods
-        const agentInfo = await this.getAgentInfo();
+        const agentInfo = await this.getAgentInfo(options);
         const tools = agentInfo.tools.map(t => ({
             name: t.name,
             description: t.description,
@@ -2585,8 +2638,15 @@ class SingleAgentClient {
                 // because normalizeAgentConfig returns early when _inProcessMcpClient is set). The
                 // executor then hits ProtocolClient.callTool which reads _inProcessMcpClient directly,
                 // so the sentinel adcp-in-process:// URI never reaches validateAgentUrl.
-                const agent = await this.ensureEndpointDiscovered();
-                const result = await this.executor.executeTask(agent, 'get_adcp_capabilities', {}, undefined);
+                const agent = await this.ensureEndpointDiscovered(options);
+                const result = await this.executor.executeTask(agent, 'get_adcp_capabilities', {}, undefined, options);
+                (0, abort_2.throwIfAborted)(options?.signal);
+                const requestTimeoutMs = (0, abort_2.resolveRequestTimeoutMs)(options?.transport?.requestTimeoutMs ?? this.config.transport?.requestTimeoutMs);
+                if (!result.success &&
+                    requestTimeoutMs !== undefined &&
+                    /\b(requesttimeout|timeout|timed out)\b/i.test(result.error ?? '')) {
+                    throw (0, abort_2.createTimeoutError)(requestTimeoutMs);
+                }
                 if (result.success && result.data) {
                     this.cachedCapabilities = (0, capabilities_1.augmentCapabilitiesFromTools)((0, capabilities_1.parseCapabilitiesResponse)(result.data), tools);
                     this.maybeWarnV2Sunset(this.cachedCapabilities);
@@ -2641,7 +2701,7 @@ class SingleAgentClient {
                     `since the agent has the v3-only discovery tool. ` +
                     `This client routes to v3 adapters, but calls reading capability details ` +
                     `(idempotency TTL, supported_versions, feature flags) will fail until the agent ` +
-                    `operator fixes the capabilities endpoint at ${this.agent.agent_uri}.`, {
+                    `operator fixes the capabilities endpoint.`, {
                     success: result.success,
                     hasError: !!result.error,
                     hasData: !!result.data,
@@ -2651,15 +2711,16 @@ class SingleAgentClient {
                 // Re-throw errors that indicate real infrastructure problems —
                 // only fall through for tool-execution failures (the agent
                 // advertises get_adcp_capabilities but can't actually serve it).
-                if (error instanceof errors_1.AuthenticationRequiredError || error instanceof errors_1.TaskTimeoutError) {
+                if (error instanceof errors_1.AuthenticationRequiredError ||
+                    error instanceof errors_1.TaskTimeoutError ||
+                    (0, abort_1.isAbortOrTimeoutError)(error)) {
                     throw error;
                 }
                 console.warn(`[AdCP] Agent "${this.agent.id}" advertises get_adcp_capabilities but the call ` +
                     `threw — treating as v3 (synthetic) since the agent has the v3-only discovery tool. ` +
                     `This client routes to v3 adapters, but calls reading capability details ` +
                     `(idempotency TTL, supported_versions, feature flags) will fail until the agent ` +
-                    `operator fixes the capabilities endpoint at ${this.agent.agent_uri}. ` +
-                    `Error: ${error instanceof Error ? error.message : String(error)}`);
+                    `operator fixes the capabilities endpoint.`);
             }
             // Synthesize v3 capabilities from the tool list. Reached only when
             // the executor returned non-v3-shaped data, OR threw a non-auth
@@ -2750,8 +2811,8 @@ class SingleAgentClient {
      *
      * @returns 'v2' or 'v3' based on server capabilities
      */
-    async detectServerVersion() {
-        const capabilities = await this.getCapabilities();
+    async detectServerVersion(options) {
+        const capabilities = await this.getCapabilities(options);
         return capabilities.version;
     }
     /**
@@ -2848,13 +2909,17 @@ class SingleAgentClient {
      *
      * Skipped when validateFeatures is false or the task has no feature requirements.
      */
-    async validateTaskFeatures(taskName) {
+    async validateTaskFeatures(taskName, options) {
         if (this.config.validateFeatures === false)
             return;
         const requiredFeatures = capabilities_1.TASK_FEATURE_MAP[taskName];
         if (!requiredFeatures || requiredFeatures.length === 0)
             return;
-        await this.require(...requiredFeatures);
+        const capabilities = await this.getCapabilities(options);
+        const missing = requiredFeatures.filter(f => !(0, capabilities_1.resolveFeature)(capabilities, f));
+        if (missing.length > 0) {
+            throw new errors_1.FeatureUnsupportedError(missing, (0, capabilities_1.listDeclaredFeatures)(capabilities), this.agent.agent_uri);
+        }
     }
     /**
      * Fail version-incompatible request shapes before schema validation.
@@ -2968,10 +3033,10 @@ class SingleAgentClient {
      *
      * Throws `VersionUnsupportedError` with the specific reason on failure.
      */
-    async requireSupportedMajor(taskType = 'request') {
+    async requireSupportedMajor(taskType = 'request', options) {
         if (this.isV2Allowed())
             return;
-        const capabilities = await this.getCapabilities();
+        const capabilities = await this.getCapabilities(options);
         // Synthetic capabilities — no authoritative `get_adcp_capabilities`
         // response, so the version + idempotency-TTL fields couldn't be read.
         // Route as the synthesized version (v2 when the v3 discovery tool is