@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/core/TaskExecutor.js

@@ -53,6 +53,8 @@ var import_client_hooks = require('../validation/client-hooks.js');
 var import_schema_validator = require('../validation/schema-validator.js');
 var import_schema_loader = require('../validation/schema-loader.js');
 var import_version = require('../version.js');
+var import_version2 = require('../negotiation/version.js');
+var import_verification = require('../negotiation/verification.js');
 var import_response_unwrapper = require('../utils/response-unwrapper.js');
 var import_error_extraction = require('../utils/error-extraction.js');
 var import_idempotency = require('../utils/idempotency.js');
@@ -687,7 +689,11 @@ class TaskExecutor {
    * adaptation runs, so the validator sees the same object the caller wrote.
    * Throws in strict, logs to `debugLogs` in warn, no-ops in off.
    */
-  validateRequest(taskName, params, debugLogs) {
+  validateRequest(taskName, params, debugLogs, adcpVersion) {
+    if (adcpVersion !== void 0) {
+      (0, import_client_hooks.validateOutgoingRequest)(taskName, params, this.requestValidationMode, debugLogs, adcpVersion);
+      return;
+    }
     if (this.config.experimentalIdentity33?.() && this.requestValidationMode !== "off") {
       const outcome = validateIdentity33Payload(taskName, "request", params, this.config.adcpVersion);
       if (!outcome.valid) {
@@ -823,6 +829,13 @@ class TaskExecutor {
       agent: { id: agent.id, name: agent.name, protocol: agent.protocol },
       serverVersion: effectiveServerVersion,
       serverVersionSynthetic: targetCapabilities?._synthetic ?? serverVersion === void 0,
+      ...taskName === "refine_proposals" && targetCapabilities?._synthetic === false && {
+        refinementServedVersion: (0, import_version2.applicableRefinementServedVersion)(
+          targetCapabilities.servedVersion,
+          params?.adcp_version ?? (0, import_version.toReleasePrecisionVersion)(wireAdcpVersion ?? this.config.adcpVersion ?? import_version.ADCP_VERSION),
+          (0, import_version.toReleasePrecisionVersion)(this.config.wireAdcpVersion ?? this.config.adcpVersion ?? import_version.ADCP_VERSION)
+        )
+      },
       idempotencyKey
     };
     this.activeTasks.set(taskId, taskState);
@@ -1113,7 +1126,8 @@ class TaskExecutor {
         dispatchSettlement?.persistPausedContinuation ?? true,
         effectiveServerVersion,
         deferredClientContext,
-        dispatchSettlement?.requireDeferredSettlementResumeAuthorization === true
+        dispatchSettlement?.requireDeferredSettlementResumeAuthorization === true,
+        taskState.refinementServedVersion
       );
       (0, import_abort.throwIfAborted)(postDispatchOptions.signal);
       if (governanceResult) {
@@ -1256,17 +1270,36 @@ class TaskExecutor {
       debug_logs: debugLogs
     };
   }
-  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const status = this.responseParser.getStatus(response);
     const serverTaskId = this.responseParser.getTaskId(response);
     const task = this.activeTasks.get(taskId);
     if (task && serverTaskId) task.serverTaskId = serverTaskId;
     switch (status) {
       case import_ProtocolResponseParser.ADCP_STATUS.COMPLETED:
-        const completedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+        const completedData = this.extractResponseData(
+          response,
+          debugLogs,
+          taskName,
+          serverVersion,
+          options.negotiatedAdcpVersion
+        );
         if (!deferTerminalTaskStatus) this.updateTaskStatus(taskId, "completed", completedData);
-        const operationSuccess = this.isOperationSuccess(completedData, taskName, serverVersion);
-        const validationResult = this.validateResponseSchema(completedData, taskName, debugLogs, serverVersion);
+        const operationSuccess = this.isOperationSuccess(
+          completedData,
+          taskName,
+          serverVersion,
+          options.negotiatedAdcpVersion
+        );
+        const validationResult = this.validateResponseSchema(
+          completedData,
+          taskName,
+          debugLogs,
+          serverVersion,
+          params,
+          refinementServedVersion,
+          options.negotiatedAdcpVersion
+        );
         const finalSuccess = operationSuccess && validationResult.valid;
         const finalError = !finalSuccess ? validationResult.errors.length > 0 ? `Schema validation failed: ${validationResult.errors.join("; ")}` : this.extractOperationError(completedData) : void 0;
         if (finalSuccess) {
@@ -1351,12 +1384,19 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       case import_ProtocolResponseParser.ADCP_STATUS.FAILED:
       case import_ProtocolResponseParser.ADCP_STATUS.REJECTED:
       case import_ProtocolResponseParser.ADCP_STATUS.CANCELED: {
-        const failedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+        const failedData = this.extractResponseData(
+          response,
+          debugLogs,
+          taskName,
+          serverVersion,
+          options.negotiatedAdcpVersion
+        );
         const failedPayload = response?.structuredContent === void 0 && response?.content === void 0 && response?.result === void 0 && response?.data != null && typeof response.data === "object" ? response.data : failedData;
         const adcpErrorInfo = (0, import_error_extraction.extractAdcpErrorInfo)(failedPayload);
         const hasStructuredError = !!adcpErrorInfo;
@@ -1384,10 +1424,29 @@ class TaskExecutor {
         };
       }
       default:
-        const defaultData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+        const defaultData = this.extractResponseData(
+          response,
+          debugLogs,
+          taskName,
+          serverVersion,
+          options.negotiatedAdcpVersion
+        );
         if (defaultData && (defaultData !== response || response.structuredContent || response.result || response.data)) {
-          const defaultSuccess = this.isOperationSuccess(defaultData, taskName, serverVersion);
-          const defaultValidation = this.validateResponseSchema(defaultData, taskName, debugLogs, serverVersion);
+          const defaultSuccess = this.isOperationSuccess(
+            defaultData,
+            taskName,
+            serverVersion,
+            options.negotiatedAdcpVersion
+          );
+          const defaultValidation = this.validateResponseSchema(
+            defaultData,
+            taskName,
+            debugLogs,
+            serverVersion,
+            params,
+            refinementServedVersion,
+            options.negotiatedAdcpVersion
+          );
           const defaultFinalSuccess = defaultSuccess && defaultValidation.valid;
           const defaultFinalError = !defaultFinalSuccess ? defaultValidation.errors.length > 0 ? `Schema validation failed: ${defaultValidation.errors.join("; ")}` : this.extractOperationError(defaultData) : void 0;
           if (defaultFinalSuccess) {
@@ -1437,7 +1496,7 @@ class TaskExecutor {
    *
    * @internal Exposed for testing purposes
    */
-  extractResponseData(response, debugLogs, toolName, serverVersion) {
+  extractResponseData(response, debugLogs, toolName, serverVersion, negotiatedAdcpVersion) {
     const a2aState = response?.result?.status?.state;
     if (a2aState === "input-required" || a2aState === "auth-required") {
       const statusParts = response?.result?.status?.message?.parts;
@@ -1478,7 +1537,7 @@ class TaskExecutor {
       }
       const unwrapped = (0, import_response_unwrapper.unwrapProtocolResponse)(response, toolName, void 0, {
         filterInvalidProducts: this.config.filterInvalidProducts,
-        responseAdcpVersion: this.effectiveResponseAdcpVersion(serverVersion)
+        responseAdcpVersion: this.effectiveResponseAdcpVersion(serverVersion, negotiatedAdcpVersion)
       });
       if (response?.structuredContent) {
         this.logDebug(debugLogs, "info", "Successfully extracted MCP data", {
@@ -1509,8 +1568,12 @@ class TaskExecutor {
    * Check if extracted response data represents a successful operation.
    * Handles singular `error`, plural `errors` (AdCP schema), and `success: false`.
    */
-  isOperationSuccess(data, taskName, serverVersion) {
-    return (0, import_response_unwrapper.isAdcpOperationSuccess)(data, taskName, this.effectiveResponseAdcpVersion(serverVersion));
+  isOperationSuccess(data, taskName, serverVersion, negotiatedAdcpVersion) {
+    return (0, import_response_unwrapper.isAdcpOperationSuccess)(
+      data,
+      taskName,
+      this.effectiveResponseAdcpVersion(serverVersion, negotiatedAdcpVersion)
+    );
   }
   /**
    * Extract a human-readable error message from response data.
@@ -1541,7 +1604,13 @@ class TaskExecutor {
    * Handle 'working' status - return as valid intermediate state
    */
   async waitForWorkingCompletion(agent, taskId, taskName, params, initialResponse, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), serverVersion = "v3") {
-    const partialData = this.extractResponseData(initialResponse, debugLogs, taskName, serverVersion);
+    const partialData = this.extractResponseData(
+      initialResponse,
+      debugLogs,
+      taskName,
+      serverVersion,
+      options.negotiatedAdcpVersion
+    );
     const metadata = this.buildMetadata({
       taskId,
       taskName,
@@ -1565,7 +1634,13 @@ class TaskExecutor {
    * Set up submitted task with webhook
    */
   async setupSubmittedTask(agent, taskId, taskName, response, messages, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, serverVersion = "v3") {
-    const partialData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+    const partialData = this.extractResponseData(
+      response,
+      debugLogs,
+      taskName,
+      serverVersion,
+      options.negotiatedAdcpVersion
+    );
     let webhookUrl = response.webhookUrl;
     if (!webhookUrl && this.config.webhookManager) {
       webhookUrl = this.config.webhookManager.generateUrl(taskId);
@@ -2001,7 +2076,7 @@ class TaskExecutor {
    * This is common for HITL (human-in-the-loop) workflows where the agent has already processed
    * the request and is just signaling that async approval may be needed.
    */
-  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, pauseStatus = "input-required", persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, pauseStatus = "input-required", persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const inputRequest = this.responseParser.parseInputRequest(response);
     const serverContextId = this.responseParser.getContextId(response) ?? response.contextId;
     const a2aTaskId = this.responseParser.getA2AContinuationTaskId(response);
@@ -2009,7 +2084,13 @@ class TaskExecutor {
     const operationRoutedContinuation = deferTerminalTaskStatus || directContinuationRecovery;
     const settlementServerTaskId = operationRoutedContinuation ? this.responseParser.getTaskId(response) : void 0;
     if (agent.protocol === "mcp" || !a2aTaskId) {
-      const partialData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+      const partialData = this.extractResponseData(
+        response,
+        debugLogs,
+        taskName,
+        serverVersion,
+        options.negotiatedAdcpVersion
+      );
       const metadata = this.buildMetadata({
         taskId,
         taskName,
@@ -2030,7 +2111,13 @@ class TaskExecutor {
       };
     }
     if (!inputHandler) {
-      const partialData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+      const partialData = this.extractResponseData(
+        response,
+        debugLogs,
+        taskName,
+        serverVersion,
+        options.negotiatedAdcpVersion
+      );
       const metadata = this.buildMetadata({
         taskId,
         taskName,
@@ -2057,8 +2144,12 @@ class TaskExecutor {
           a2aTaskId,
           serverVersion,
           ...options.wireAdcpVersion !== void 0 && { wireAdcpVersion: options.wireAdcpVersion },
+          ...options.negotiatedAdcpVersion !== void 0 && {
+            negotiatedAdcpVersion: options.negotiatedAdcpVersion
+          },
           ...options.versionEnvelope !== void 0 && { versionEnvelope: options.versionEnvelope },
           serverVersionSynthetic: this.activeTasks.get(taskId)?.serverVersionSynthetic,
+          ...refinementServedVersion !== void 0 && { refinementServedVersion },
           agentId: agent.id,
           taskName,
           params: durableDeferredSnapshot(params),
@@ -2123,7 +2214,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       };
       const deferred = {
@@ -2199,8 +2291,12 @@ class TaskExecutor {
           a2aTaskId,
           serverVersion,
           ...options.wireAdcpVersion !== void 0 && { wireAdcpVersion: options.wireAdcpVersion },
+          ...options.negotiatedAdcpVersion !== void 0 && {
+            negotiatedAdcpVersion: options.negotiatedAdcpVersion
+          },
           ...options.versionEnvelope !== void 0 && { versionEnvelope: options.versionEnvelope },
           serverVersionSynthetic: this.activeTasks.get(taskId)?.serverVersionSynthetic,
+          ...refinementServedVersion !== void 0 && { refinementServedVersion },
           agentId: agent.id,
           taskName,
           params: durableDeferredSnapshot(params),
@@ -2266,7 +2362,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       };
       const deferred = {
@@ -2317,7 +2414,8 @@ class TaskExecutor {
       persistPausedContinuation,
       serverVersion,
       deferredClientContext,
-      requireDeferredSettlementResumeAuthorization
+      requireDeferredSettlementResumeAuthorization,
+      refinementServedVersion
     );
   }
   /**
@@ -2533,7 +2631,12 @@ class TaskExecutor {
         });
       }
       if (status.status === import_ProtocolResponseParser.ADCP_STATUS.COMPLETED) {
-        const pollSuccess = this.isOperationSuccess(status.result, status.taskType, serverVersion);
+        const pollSuccess = this.isOperationSuccess(
+          status.result,
+          status.taskType,
+          serverVersion,
+          metadataTaskId ? this.activeTasks.get(metadataTaskId)?.options.negotiatedAdcpVersion : void 0
+        );
         if (pollSuccess) {
           return markAuthoritativePolledTerminal(
             (0, import_match.attachMatch)({
@@ -3088,6 +3191,7 @@ class TaskExecutor {
         state.messages,
         {
           ...state.wireAdcpVersion !== void 0 && { wireAdcpVersion: state.wireAdcpVersion },
+          ...state.negotiatedAdcpVersion !== void 0 && { negotiatedAdcpVersion: state.negotiatedAdcpVersion },
           ...state.versionEnvelope !== void 0 && { versionEnvelope: state.versionEnvelope }
         },
         [],
@@ -3309,6 +3413,7 @@ class TaskExecutor {
         // No handler for deferred tasks - input was provided by human
         {
           ...state.wireAdcpVersion !== void 0 && { wireAdcpVersion: state.wireAdcpVersion },
+          ...state.negotiatedAdcpVersion !== void 0 && { negotiatedAdcpVersion: state.negotiatedAdcpVersion },
           ...state.versionEnvelope !== void 0 && { versionEnvelope: state.versionEnvelope }
         },
         [],
@@ -3317,7 +3422,8 @@ class TaskExecutor {
         false,
         state.serverVersion,
         state.clientContext,
-        state.settlementResumeAuthorizationRequired === true
+        state.settlementResumeAuthorizationRequired === true,
+        state.refinementServedVersion
       );
       resumed = attachDeferredServerVersion(resumed, state);
       const observedResumedServerTaskId = resumed.metadata.serverTaskId;
@@ -3343,7 +3449,11 @@ class TaskExecutor {
           ...resumed.metadata.contextId !== void 0 ? { contextId: resumed.metadata.contextId } : state.contextId !== void 0 ? { contextId: state.contextId } : {},
           a2aTaskId: nextA2ATaskId,
           serverVersion: state.serverVersion,
+          ...state.refinementServedVersion !== void 0 && {
+            refinementServedVersion: state.refinementServedVersion
+          },
           ...state.wireAdcpVersion !== void 0 && { wireAdcpVersion: state.wireAdcpVersion },
+          ...state.negotiatedAdcpVersion !== void 0 && { negotiatedAdcpVersion: state.negotiatedAdcpVersion },
           ...state.versionEnvelope !== void 0 && { versionEnvelope: state.versionEnvelope },
           ...state.serverVersionSynthetic !== void 0 && {
             serverVersionSynthetic: state.serverVersionSynthetic
@@ -4271,7 +4381,7 @@ class TaskExecutor {
   /**
    * Continue a task after receiving input
    */
-  async continueTaskWithInput(agent, taskId, taskName, params, contextId, a2aTaskId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async continueTaskWithInput(agent, taskId, taskName, params, contextId, a2aTaskId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const inputSnapshot = structuredClone(input);
     if (agent.protocol !== "a2a") {
       throw new Error("MCP does not define a standard continuation for a returned input-required task.");
@@ -4337,7 +4447,8 @@ class TaskExecutor {
       persistPausedContinuation,
       serverVersion,
       deferredClientContext,
-      requireDeferredSettlementResumeAuthorization
+      requireDeferredSettlementResumeAuthorization,
+      refinementServedVersion
     );
   }
   /**
@@ -4529,11 +4640,11 @@ class TaskExecutor {
    * valid so the caller can continue. Off mode short-circuits before
    * AJV runs.
    */
-  validateResponseSchema(response, taskName, debugLogs, serverVersion) {
+  validateResponseSchema(response, taskName, debugLogs, serverVersion, requestParams, refinementServedVersion, negotiatedAdcpVersion) {
     const mode = this.responseValidationMode;
     const logViolations = this.config.logSchemaViolations !== false;
     try {
-      const pinnedValidationVersion = this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
+      const pinnedValidationVersion = this.responseAdcpVersionForValidation() ?? negotiatedAdcpVersion ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
       if (taskName === "get_adcp_capabilities") {
         return (0, import_schema_loader.withServedValidationVersion)(
           response,
@@ -4541,6 +4652,46 @@ class TaskExecutor {
           (validationVersion) => this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion)
         );
       }
+      if (taskName === "refine_proposals" && mode !== "off") {
+        const ceiling = requestParams?.adcp_version ?? (0, import_version.toReleasePrecisionVersion)(this.config.wireAdcpVersion ?? pinnedValidationVersion);
+        const issues = [];
+        const selected = (0, import_verification.selectRefinementSchemaVersion)(
+          ceiling,
+          response,
+          {
+            adcpVersion: pinnedValidationVersion,
+            servedAdcpVersion: (0, import_version2.applicableRefinementServedVersion)(refinementServedVersion, ceiling)
+          },
+          issues
+        );
+        if (!selected) {
+          const errors = issues.map((issue) => `${issue.path}: ${issue.message}`);
+          if (logViolations) {
+            debugLogs.push({
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              type: mode === "strict" ? "error" : "warning",
+              message: `Schema validation ${mode === "strict" ? "failed" : "warning"} for ${taskName}: ${errors.join("; ")}`,
+              errors,
+              issues,
+              schemaVersion: pinnedValidationVersion,
+              mode
+            });
+            if (mode === "warn") {
+              console.warn(
+                `Schema validation failed for ${taskName} against AdCP ${pinnedValidationVersion} (non-blocking):`,
+                errors
+              );
+            } else {
+              console.error(
+                `Schema validation failed for ${taskName} against AdCP ${pinnedValidationVersion}:`,
+                errors
+              );
+            }
+          }
+          return { valid: mode !== "strict", errors: mode === "strict" ? errors : [] };
+        }
+        return this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, selected);
+      }
       return this.validateResponseSchemaAgainst(
         response,
         taskName,
@@ -4595,8 +4746,8 @@ class TaskExecutor {
     if (this.config.versionEnvelope === "major-only") return "3.0";
     return void 0;
   }
-  effectiveResponseAdcpVersion(serverVersion) {
-    return this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
+  effectiveResponseAdcpVersion(serverVersion, negotiatedAdcpVersion) {
+    return this.responseAdcpVersionForValidation() ?? negotiatedAdcpVersion ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
   }
   /**
    * Update task status and emit events