@adcp/sdk 9.0.0-beta.29 → 9.0.0-beta.31

package/dist/lib/core/SingleAgentClient.js

@@ -41,6 +41,7 @@ const schemas = __importStar(require("../types/schemas.generated"));
 const adcp_1 = require("../types/adcp");
 const version_1 = require("../version");
 const adcp_version_config_1 = require("../utils/adcp-version-config");
+const version_2 = require("../adapters/version");
 const idempotency_1 = require("../utils/idempotency");
 const TaskExecutor_1 = require("./TaskExecutor");
 const match_1 = require("./match");
@@ -1045,6 +1046,10 @@ class SingleAgentClient {
             skipAccountValidation: options?.skipAccountValidation,
         });
         this.assertRequestSupportedByConfiguredVersion(taskType, normalizedParams, options);
+        // Degrade an auto-injected discovery webhook to polling for pre-3.1 pins
+        // (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(taskType, options);
         // Inject an idempotency_key for mutating tools before schema validation
         // so callers don't have to supply one. TaskExecutor also guards against
         // missing keys, but validation happens here first — do the injection up
@@ -1088,27 +1093,32 @@ class SingleAgentClient {
         if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation) {
             this.executor.validateRequest(taskType, normalizedParams);
         }
-        // Adapt request for v2 servers if needed
+        // Adapt request for the detected server and AdCP protocol versions.
         const serverVersion = await this.detectServerVersion();
-        const adaptedParams = await this.adaptRequestForServerVersion(taskType, normalizedParams);
+        const inputSchemaStripLogs = [];
+        const { params: adaptedParams, driftLogs: adaptDriftLogs } = this.adaptRequest(taskType, normalizedParams, serverVersion, inputSchemaStripLogs);
         // Symmetric to the pre-adapter v3 pass above: when the adapter
         // rewrote the request for a v2 server, warn-validate the adapted
         // shape against the cached v2.5 schema bundle. Drift gets collected
         // here and merged into result.metadata.debug_logs after executeTask
         // returns — without that merge the warning would silently drop on
         // the floor and adapter drift would land in production unnoticed.
-        const v25DriftLogs = [];
+        const v25DriftLogs = [...adaptDriftLogs];
+        if (webhookDriftLog)
+            v25DriftLogs.push(webhookDriftLog);
         if (serverVersion === 'v2') {
             this.executor.validateAdaptedRequestAgainstV2(taskType, adaptedParams, v25DriftLogs);
         }
-        let result = await this.executor.executeTask(agent, taskType, adaptedParams, inputHandler, options, serverVersion);
+        let result = await this.executor.executeTask(agent, taskType, adaptedParams, inputHandler, effectiveOptions, serverVersion);
         // Merge collected drift into the executor's debug_logs so adopters
-        // reading result.debug_logs see post-adapter v2.5 warnings alongside
+        // reading result.debug_logs see input-schema stripping, post-adapter
+        // v2.5 warnings, and any pre-3.1 webhook-degradation notice alongside
         // the executor's own logs. On error paths the executor may not surface
-        // result.debug_logs at all — drift collected before the failure is
+        // result.debug_logs at all; logs collected before the failure are
         // dropped, matching the executor's own debug-log behavior.
-        if (v25DriftLogs.length > 0) {
-            result.debug_logs = [...(result.debug_logs ?? []), ...v25DriftLogs];
+        const postAdapterLogs = [...inputSchemaStripLogs, ...v25DriftLogs];
+        if (postAdapterLogs.length > 0) {
+            result.debug_logs = [...(result.debug_logs ?? []), ...postAdapterLogs];
         }
         // Normalize response to v3 format
         if (result.success && result.data) {
@@ -1428,15 +1438,19 @@ class SingleAgentClient {
         };
     }
     /**
-     * Adapt request parameters for the detected server version
+     * Adapt a request for the detected server wire version and the seller's
+     * AdCP protocol version. Applies wire-format adapters (v2.5) when talking
+     * to a v2 server, then applies protocol-version adapters (e.g. stripping
+     * 3.1-only fields for a 3.0 seller). Returns the adapted params and any
+     * drift log entries describing what was changed.
      *
-     * Converts v3-style requests to v2 format when talking to v2 servers.
+     * Runs after `detectServerVersion` so `cachedCapabilities` is populated
+     * and the protocol-version adapters see the seller's declared caps.
      */
-    async adaptRequestForServerVersion(taskType, params) {
-        // Get server version (cached after first call)
-        const version = await this.detectServerVersion();
+    adaptRequest(taskType, params, serverVersion, debugLogs) {
+        const driftLogs = [];
         let adapted = params;
-        if (version !== 'v3') {
+        if (serverVersion !== 'v3') {
             // Dispatch through the legacy v2.5 adapter registry. Per-tool pairs
             // live in `src/lib/adapters/legacy/v2-5/<tool>.ts`. Tools without a
             // registered pair (or pairs whose request side is pass-through)
@@ -1445,7 +1459,7 @@ class SingleAgentClient {
             // this dispatch.
             const pair = (0, v2_5_1.getV25Adapter)(taskType);
             if (pair)
-                adapted = pair.adaptRequest(params);
+                adapted = pair.adaptRequest(adapted);
         }
         // Strip any top-level fields not declared in the agent's tool schema.
         // This handles partial implementations (agents that omit some fields)
@@ -1469,49 +1483,82 @@ class SingleAgentClient {
         // (e.g. `applyBrandInvariant` in the storyboard runner — see #940),
         // not to lean on this strip path as a backstop.
         const toolSchema = this.cachedToolSchemas?.get(taskType);
-        if (!toolSchema || Object.keys(toolSchema).length === 0)
-            return adapted;
-        const declaredFields = new Set(Object.keys(toolSchema));
-        // The v2 adapter may rename fields (e.g. brand → brand_manifest) that a
-        // v3 server — misdetected as v2 — doesn't declare. Reconcile known
-        // adapter mappings so the value isn't silently dropped.
-        //
-        // CRITICAL: only alias when the JS type of the moved value is
-        // compatible with the destination field's declared shape. v2.5 sellers
-        // (e.g. Wonderstruck) declare `brand` in their tool schema as a
-        // BrandReference object — v2 adapter produces a `brand_manifest` URL
-        // string, and blindly aliasing the string into the object slot causes
-        // the seller to reject with `Input should be a valid dictionary or
-        // instance of BrandReference`. Skip the alias when shapes don't match
-        // and let the field-stripping path drop the v2-shaped value cleanly.
-        const adapterAliases = [['brand_manifest', 'brand']];
-        for (const [adapterField, schemaField] of adapterAliases) {
-            if (adapted[adapterField] !== undefined &&
-                !declaredFields.has(adapterField) &&
-                declaredFields.has(schemaField) &&
-                adapted[schemaField] === undefined &&
-                valueMatchesSchemaType(adapted[adapterField], toolSchema[schemaField])) {
-                adapted[schemaField] = adapted[adapterField];
-                delete adapted[adapterField];
+        if (toolSchema && Object.keys(toolSchema).length > 0) {
+            const declaredFields = new Set(Object.keys(toolSchema));
+            // The v2 adapter may rename fields (e.g. brand → brand_manifest) that a
+            // v3 server — misdetected as v2 — doesn't declare. Reconcile known
+            // adapter mappings so the value isn't silently dropped.
+            //
+            // CRITICAL: only alias when the JS type of the moved value is
+            // compatible with the destination field's declared shape. v2.5 sellers
+            // (e.g. Wonderstruck) declare `brand` in their tool schema as a
+            // BrandReference object — v2 adapter produces a `brand_manifest` URL
+            // string, and blindly aliasing the string into the object slot causes
+            // the seller to reject with `Input should be a valid dictionary or
+            // instance of BrandReference`. Skip the alias when shapes don't match
+            // and let the field-stripping path drop the v2-shaped value cleanly.
+            const adapterAliases = [['brand_manifest', 'brand']];
+            for (const [adapterField, schemaField] of adapterAliases) {
+                if (adapted[adapterField] !== undefined &&
+                    !declaredFields.has(adapterField) &&
+                    declaredFields.has(schemaField) &&
+                    adapted[schemaField] === undefined &&
+                    valueMatchesSchemaType(adapted[adapterField], toolSchema[schemaField])) {
+                    adapted[schemaField] = adapted[adapterField];
+                    delete adapted[adapterField];
+                }
             }
-        }
-        // Protocol envelope fields are always preserved — they live at the
-        // protocol layer, not in individual tool schemas.
-        const envelopeFields = adcp_1.ADCP_ENVELOPE_FIELDS;
-        const filtered = {};
-        const stripped = [];
-        for (const [key, value] of Object.entries(adapted)) {
-            if (declaredFields.has(key) || envelopeFields.has(key)) {
-                filtered[key] = value;
+            // Protocol envelope fields are always preserved — they live at the
+            // protocol layer, not in individual tool schemas.
+            const envelopeFields = adcp_1.ADCP_ENVELOPE_FIELDS;
+            const filtered = {};
+            const schemaStripped = [];
+            for (const [key, value] of Object.entries(adapted)) {
+                if (declaredFields.has(key) || envelopeFields.has(key)) {
+                    filtered[key] = value;
+                }
+                else {
+                    schemaStripped.push(key);
+                }
             }
-            else {
-                stripped.push(key);
+            if (schemaStripped.length > 0) {
+                console.warn(`[AdCP] Stripping fields not declared in agent "${this.agent.id}" schema for ${taskType}: ${schemaStripped.join(', ')}`);
+                debugLogs?.push({
+                    type: 'warning',
+                    message: `Stripped fields not declared in agent tool input schema for ${taskType}: ${schemaStripped.join(', ')}`,
+                    timestamp: new Date().toISOString(),
+                    details: {
+                        code: 'input_schema_field_stripped',
+                        task: taskType,
+                        fields: schemaStripped,
+                        agent_id: this.agent.id,
+                    },
+                });
+            }
+            adapted = filtered;
+        }
+        // Protocol version adaptation: strip fields not accepted by the target
+        // AdCP version. `resolveAdapterKey` returns the effective target version
+        // based on the client pin and the seller's advertised caps; adapters live
+        // in `src/lib/adapters/version/<target>/`.
+        const adapterKey = (0, version_2.resolveAdapterKey)(this.resolvedAdcpVersion, this.cachedCapabilities);
+        if (adapterKey) {
+            const versionAdapter = (0, version_2.getVersionAdapter)(adapterKey, taskType);
+            if (versionAdapter) {
+                const result = versionAdapter.adaptRequest(adapted);
+                adapted = result.params;
+                if (result.drift) {
+                    driftLogs.push({
+                        ...result.drift,
+                        taskName: taskType,
+                        clientVersion: this.resolvedAdcpVersion,
+                        targetVersion: adapterKey,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
             }
         }
-        if (stripped.length > 0) {
-            console.warn(`[AdCP] Stripping fields not declared in agent "${this.agent.id}" schema for ${taskType}: ${stripped.join(', ')}`);
-        }
-        return filtered;
+        return { params: adapted, driftLogs };
     }
     /**
      * Normalize response to v3 format
@@ -1955,6 +2002,10 @@ class SingleAgentClient {
                 skipAccountValidation: options?.skipAccountValidation,
             });
             this.assertRequestSupportedByConfiguredVersion(taskName, normalizedParams, options);
+            // Degrade an auto-injected discovery webhook to polling for pre-3.1 pins
+            // (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);
             if (this.config.requireV3ForMutations && (0, idempotency_1.isMutatingTask)(taskName)) {
                 await this.requireSupportedMajor(taskName);
@@ -1968,20 +2019,23 @@ class SingleAgentClient {
             if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation) {
                 this.executor.validateRequest(taskName, normalizedParams);
             }
-            // Adapt request for the server's protocol version (e.g. strip v3-only
-            // fields like buying_mode when talking to v2 agents).
+            // Adapt request for the detected server and AdCP protocol versions.
             const serverVersion = await this.detectServerVersion();
-            const adaptedParams = await this.adaptRequestForServerVersion(taskName, normalizedParams);
+            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.
             // Drift gets surfaced via result.metadata.debug_logs so adapter
             // regressions in production aren't silently swallowed.
-            const v25DriftLogs = [];
+            const v25DriftLogs = [...adaptDriftLogs];
+            if (webhookDriftLog)
+                v25DriftLogs.push(webhookDriftLog);
             if (serverVersion === 'v2') {
                 this.executor.validateAdaptedRequestAgainstV2(taskName, adaptedParams, v25DriftLogs);
             }
-            let result = await this.executor.executeTask(agent, taskName, adaptedParams, inputHandler, options, serverVersion);
-            if (v25DriftLogs.length > 0) {
-                result.debug_logs = [...(result.debug_logs ?? []), ...v25DriftLogs];
+            let result = await this.executor.executeTask(agent, taskName, adaptedParams, inputHandler, effectiveOptions, serverVersion);
+            const postAdapterLogs = [...inputSchemaStripLogs, ...v25DriftLogs];
+            if (postAdapterLogs.length > 0) {
+                result.debug_logs = [...(result.debug_logs ?? []), ...postAdapterLogs];
             }
             // Normalize response to v3 format for consistent API surface
             if (result.success && result.data) {
@@ -2518,7 +2572,7 @@ class SingleAgentClient {
         }));
         // Cache raw tool schemas for field-level compatibility checks (e.g. buying_mode on get_products).
         // INVARIANT: must be assigned before cachedCapabilities below so that any code path
-        // reaching adaptRequestForServerVersion always finds the schemas populated.
+        // reaching adaptRequest always finds the schemas populated.
         this.cachedToolSchemas = new Map(agentInfo.tools
             .filter(t => t.inputSchema?.properties)
             .map(t => [t.name, t.inputSchema.properties]));
@@ -2808,19 +2862,22 @@ class SingleAgentClient {
      * result set. A pre-3.1 client pin should not silently drop those controls
      * or let a generic schema error hide the recovery path.
      */
-    assertRequestSupportedByConfiguredVersion(taskName, params, options) {
+    assertRequestSupportedByConfiguredVersion(taskName, params, _options) {
         if (!(0, adcp_version_config_1.isPre31AdcpVersion)(this.resolvedAdcpVersion))
             return;
         const request = params && typeof params === 'object' && !Array.isArray(params) ? params : {};
-        const willInjectDiscoveryWebhook = !options?.disableWebhook && (0, webhook_url_1.selectWebhookTemplate)(this.config.webhookUrlTemplate, taskName) !== undefined;
         if (taskName === 'get_signals' && request.discovery_mode === 'wholesale') {
             this.throwPre31UnsupportedFeature(taskName, 'discovery_mode', 'get_signals.discovery_mode=wholesale', {
                 capabilityPath: 'signals.discovery_modes',
                 suffix: 'Probe get_adcp_capabilities at signals.discovery_modes before issuing wholesale calls.',
             });
         }
-        if ((taskName === 'get_products' || taskName === 'get_signals') &&
-            (request.push_notification_config !== undefined || willInjectDiscoveryWebhook)) {
+        // An EXPLICIT push_notification_config on a discovery task is caller misuse
+        // while hard-pinned <3.1: surface it rather than silently dropping the
+        // caller's webhook. An AUTO-injected discovery webhook (from
+        // `webhookUrlTemplate`) is degraded to polling instead; see
+        // `suppressPre31DiscoveryWebhook`.
+        if ((taskName === 'get_products' || taskName === 'get_signals') && request.push_notification_config !== undefined) {
             this.throwPre31UnsupportedFeature(taskName, 'push_notification_config', `${taskName}.push_notification_config`, {
                 capabilityPath: 'adcp.supported_versions',
                 suffix: 'Probe get_adcp_capabilities at adcp.supported_versions before relying on discovery task webhooks.',
@@ -2831,6 +2888,43 @@ class SingleAgentClient {
         // probes, and pre-3.1 sellers may safely ignore them and return the full
         // payload.
     }
+    /**
+     * Degrade the auto-injected get_products / get_signals discovery webhook to
+     * polling when the client is pinned below 3.1. Discovery-task
+     * `push_notification_config` is an AdCP 3.1 feature; a pre-3.1 seller would
+     * reject it. Rather than throwing on the library's own auto-injected webhook
+     * (which the caller never asked for), suppress it via `disableWebhook` and
+     * record a `pre31_webhook_degraded` drift entry so the loss of push is
+     * visible in `debug_logs`.
+     *
+     * Returns the effective options (a `disableWebhook` copy when suppressing,
+     * otherwise the caller's unchanged) and an optional drift log to merge into
+     * the result. Explicit caller-supplied `push_notification_config` is handled
+     * by `assertRequestSupportedByConfiguredVersion` (it throws) and never
+     * reaches here.
+     */
+    suppressPre31DiscoveryWebhook(taskName, options) {
+        if (!(0, adcp_version_config_1.isPre31AdcpVersion)(this.resolvedAdcpVersion))
+            return { options };
+        if (taskName !== 'get_products' && taskName !== 'get_signals')
+            return { options };
+        if (options?.disableWebhook)
+            return { options };
+        if ((0, webhook_url_1.selectWebhookTemplate)(this.config.webhookUrlTemplate, taskName) === undefined)
+            return { options };
+        return {
+            options: { ...options, disableWebhook: true },
+            driftLog: {
+                type: 'pre31_webhook_degraded',
+                message: `${taskName} discovery webhook degraded to polling: discovery-task push_notification_config ` +
+                    `requires AdCP 3.1, but this client is pinned to ${this.resolvedAdcpVersion}. ` +
+                    'The seller will not receive a push webhook; poll for the result instead.',
+                timestamp: new Date().toISOString(),
+                taskName,
+                clientVersion: this.resolvedAdcpVersion,
+            },
+        };
+    }
     throwPre31UnsupportedFeature(taskName, field, feature, opts) {
         throw new errors_1.ProtocolFeatureUnsupportedError([feature], [], this.agent.agent_uri, {
             message: `${taskName} ${field} requires AdCP 3.1 or later; ` +
@@ -2986,7 +3080,7 @@ class SingleAgentClient {
      * but unknown top-level keys pass through. This matters because callers —
      * including the storyboard runner's `applyBrandInvariant` — inject
      * scoping fields (`brand`, `account`) onto every outgoing request, and
-     * `adaptRequestForServerVersion` strips those fields downstream for tools
+     * `adaptRequest` strips those fields downstream for tools
      * whose schema doesn't declare them. A strict parse here rejects the
      * injected fields before the adapter gets a chance to clean them up, so
      * the two passes have to agree on "extra keys are fine."