@adcp/sdk 14.0.0-beta.5 → 14.0.0-beta.6

package/dist/lib/core/SingleAgentClient.mjs

@@ -13,8 +13,17 @@ import { isExternalSchemaRootActive, schemaAllowsTopLevelField } from "../valida
 import { generateIdempotencyKey, requestUsesIdempotency } from "../utils/idempotency.mjs";
 import { A2AClient as A2AClientImpl } from "@a2a-js/sdk/client";
 const A2AClient = A2AClientImpl;
-import { TaskExecutor, BeforeProtocolDispatchHookError } from "./TaskExecutor.mjs";
+import {
+  TaskExecutor,
+  AfterProtocolDispatchHookError,
+  BeforeProtocolDispatchHookError
+} from "./TaskExecutor.mjs";
 import { attachMatch } from "./match.mjs";
+import {
+  assertNativeRequestProposalsResult,
+  assertNativeRequestProposalsTask,
+  guardNativeRequestProposalsCompletion
+} from "./request-proposals-guard.mjs";
 import { withTaskDeadline } from "./task-deadline.mjs";
 import { createMCPRequestHeaders } from "../auth/index.mjs";
 import { isAbortOrTimeoutError } from "../protocols/abort.mjs";
@@ -170,6 +179,26 @@ const CANONICAL_CREATIVE_ACTIVITY_TASKS = /* @__PURE__ */ new Set([
   "get_media_buy_delivery",
   "get_creative_delivery"
 ]);
+const RECORDLESS_HMAC_READ_ONLY_TASKS = /* @__PURE__ */ new Set([
+  "get_adcp_capabilities",
+  "list_products",
+  "list_creative_formats",
+  "preview_creative",
+  "list_transformers",
+  "list_creatives",
+  "get_media_buys",
+  "get_media_buy_delivery",
+  "media_buy_delivery",
+  "get_creative_delivery",
+  "get_signals",
+  "list_accounts",
+  "get_property_list",
+  "list_property_lists",
+  "list_content_standards",
+  "get_content_standards",
+  "si_get_offering",
+  "get_plan_audit_logs"
+]);
 const TASK_SCOPED_STATE_LIMIT = 1e4;
 const CANONICAL_PACKAGE_ROUTE_TASKS = /* @__PURE__ */ new Set(["create_media_buy", "update_media_buy", "get_media_buys"]);
 const canonicalCreativeRoutingSnapshots = /* @__PURE__ */ new WeakSet();
@@ -637,6 +666,8 @@ class SingleAgentClient {
       agentId: agent.id,
       webhookSecret: config.webhookSecret,
       onWebhookRegistration: (registration) => this.persistWebhookRegistration(registration),
+      onDurableSettlementRequired: (operationId) => this.markWebhookDurableSettlementRequired(operationId),
+      externalTaskSettlementRetentionMs: registrationTtl * 1e3,
       strictSchemaValidation: config.validation?.strictSchemaValidation !== false,
       // Default: true
       logSchemaViolations: config.validation?.logSchemaViolations !== false,
@@ -704,10 +735,14 @@ class SingleAgentClient {
         this.canonicalCreativeTaskAssociations.delete(args.operationId);
       }
     }
+    const persistedAgentUrl = new URL(args.agent.agent_uri);
+    persistedAgentUrl.username = "";
+    persistedAgentUrl.password = "";
+    persistedAgentUrl.hash = "";
     try {
       await this.webhookRegistrationStore.putIfAbsent({
         agentId: args.agent.id,
-        agentUrl: args.agent.agent_uri,
+        agentUrl: persistedAgentUrl.toString(),
         protocol: args.agent.protocol,
         operationId: args.operationId,
         taskType: args.taskType,
@@ -722,6 +757,15 @@ class SingleAgentClient {
       if (args.mode === "rfc9421") throw cause;
     }
   }
+  async markWebhookDurableSettlementRequired(operationId) {
+    const mark = this.webhookRegistrationStore.markRequiresDurableSettlement;
+    if (!mark) {
+      throw new ConfigurationError(
+        "A custom webhookRegistrationStore must implement markRequiresDurableSettlement for durable mutation callbacks."
+      );
+    }
+    await mark.call(this.webhookRegistrationStore, this.agent.id, operationId);
+  }
   webhookJwksFor(registration) {
     const configured = this.config.webhookVerification?.jwks;
     if (configured) return configured;
@@ -1446,7 +1490,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       try {
         registration = await this.webhookRegistrationStore.get(this.agent.id, trustedOperationId);
       } catch (cause) {
-        if (!this.config.webhookSecret) {
+        const routedTaskType2 = options.taskType && options.taskType !== "unknown" ? options.taskType : void 0;
+        if (!this.config.webhookSecret || routedTaskType2 === void 0 || !RECORDLESS_HMAC_READ_ONLY_TASKS.has(routedTaskType2)) {
           return {
             ok: false,
             code: "webhook_registration_store_unavailable",
@@ -1472,8 +1517,29 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           message: "Webhook registration state contains invalid timestamps."
         };
       }
+      try {
+        const registeredAgentUrl = new URL(registration.agentUrl);
+        if (registeredAgentUrl.username || registeredAgentUrl.password) {
+          throw new TypeError("Webhook registration seller URL contains userinfo.");
+        }
+      } catch (cause) {
+        return {
+          ok: false,
+          code: "webhook_registration_store_unavailable",
+          message: "Webhook registration state contains an invalid seller URL.",
+          cause
+        };
+      }
       if (registration.expiresAt <= nowMs) registration = void 0;
     }
+    const trustedRouteTaskType = options.taskType && options.taskType !== "unknown" ? options.taskType : void 0;
+    if (!registration && this.config.webhookSecret && (trustedRouteTaskType === void 0 || !RECORDLESS_HMAC_READ_ONLY_TASKS.has(trustedRouteTaskType))) {
+      return {
+        ok: false,
+        code: "webhook_registration_store_unavailable",
+        message: "A trusted webhook registration is required for this task type."
+      };
+    }
     if (authHeaders.hasRfc9421 && !trustedOperationId) {
       return {
         ok: false,
@@ -1728,7 +1794,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           message: canonicalMessage,
           previewHandler,
           timestamp: normalizedPayload.timestamp,
-          idempotencyKey: normalizedPayload.idempotency_key
+          idempotencyKey: normalizedPayload.idempotency_key,
+          requiresDurableSettlement: registration?.requiresDurableSettlement
         }
       };
     } catch (error) {
@@ -1793,8 +1860,52 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         canonicalResult,
         metadata
       );
-      const webhookResult = policyDispatch.result;
+      let webhookResult = policyDispatch.result;
       metadata = policyDispatch.metadata;
+      if (metadata.task_type === "request_proposals") {
+        assertNativeRequestProposalsResult(webhookResult);
+      }
+      if (parsed.metadata.requiresDurableSettlement === true && !this.executor.hasExternalTaskSettlementRoute(metadata.operation_id)) {
+        throw new WebhookDispatchError(
+          "webhook_durable_settlement_unavailable",
+          "The callback requires durable mutation settlement, but no recoverable settlement route is available."
+        );
+      }
+      const externalStatus = await this.executor.observeExternalTaskStatus(
+        metadata.operation_id,
+        metadata.status,
+        webhookResult,
+        { serverTaskId: metadata.task_id, taskType: metadata.task_type }
+      );
+      if (externalStatus.duplicate) {
+        metadata = {
+          ...metadata,
+          status: externalStatus.status ?? metadata.status,
+          ...externalStatus.error !== void 0 && { message: externalStatus.error }
+        };
+        const duplicateActivity = {
+          type: "webhook_duplicate",
+          operation_id: metadata.operation_id,
+          agent_id: metadata.agent_id,
+          context_id: metadata.context_id,
+          task_id: metadata.task_id,
+          task_type: metadata.task_type,
+          status: metadata.status,
+          idempotency_key: metadata.idempotency_key,
+          timestamp: metadata.timestamp
+        };
+        await this.config.onActivity?.(canonicalCreativeActivity(duplicateActivity));
+        await this.asyncHandler?.handleDurableSettlementDuplicate(metadata);
+        return true;
+      }
+      if (externalStatus.settled) {
+        webhookResult = externalStatus.result;
+        metadata = {
+          ...metadata,
+          status: externalStatus.status ?? metadata.status,
+          ...externalStatus.error !== void 0 && { message: externalStatus.error }
+        };
+      }
       await this.config.onActivity?.(
         canonicalCreativeActivity({
           type: "webhook_received",
@@ -1804,7 +1915,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           task_id: metadata.task_id,
           task_type: metadata.task_type,
           status: metadata.status,
-          payload: canonicalResult,
+          payload: webhookResult,
           timestamp: metadata.timestamp
         })
       );
@@ -1819,11 +1930,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       }
       return false;
     } finally {
-      this.executor.observeExternalTaskStatus(
-        metadata.operation_id,
-        metadata.status,
-        metadata.rawHTTPPayload
-      );
       this.forgetProductPolicyRequestParams(metadata);
     }
   }
@@ -2080,7 +2186,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           res.end(JSON.stringify({ status: "accepted", received: handled }));
         }
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorMessage = error instanceof WebhookDispatchError ? error.message : "Webhook could not be processed.";
         const statusCode = webhookErrorHttpStatus(error);
         if (res.json) {
           res.status(statusCode).json({ error: errorMessage });
@@ -3299,9 +3405,10 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   }
   /** @internal Run deterministic legacy-create preflight before the caller atomically claims its mutation. */
   async createMediaBuyLegacyWithPreDispatch(params, beforeDispatch, inputHandler, options) {
+    const requestSnapshot = structuredClone(params);
     return this.executeTaskUnprojected(
       "create_media_buy",
-      params,
+      requestSnapshot,
       inputHandler,
       options,
       "onCreateMediaBuyStatusChange",
@@ -3991,6 +4098,10 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         return this.getMediaBuyDelivery(params, inputHandler, options);
       case "get_creative_delivery":
         return this.getCreativeDelivery(params, inputHandler, options);
+      case "request_proposals":
+        return guardNativeRequestProposalsCompletion(
+          await this.executeTaskUnprojected(taskName, params, inputHandler, options)
+        );
     }
     return this.executeTaskUnprojected(taskName, params, inputHandler, options);
   }
@@ -4096,7 +4207,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       result = await this.applyProductPropertyPolicy(result, taskName, normalizedParams);
       return result;
     } catch (error) {
-      if (error instanceof BeforeProtocolDispatchHookError) throw error.original;
+      if (error instanceof BeforeProtocolDispatchHookError || error instanceof AfterProtocolDispatchHookError) {
+        throw error.original;
+      }
       if (error instanceof AuthenticationRequiredError || error instanceof TaskTimeoutError || error instanceof VersionUnsupportedError || error instanceof FeatureUnsupportedError || isAbortOrTimeoutError(error)) {
         throw error;
       }
@@ -4364,6 +4477,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    */
   getActiveTasks() {
     return this.executor.getActiveTasks().filter((task) => task.agent.id === this.agent.id).map((task) => {
+      assertNativeRequestProposalsTask(task);
       if (!CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskName)) return task;
       const converter = this.resolveLegacyFormatConverter(
         this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter
@@ -4398,12 +4512,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   async listTasks() {
     const tasks = await this.executor.getTaskList(this.agent.id);
     return tasks.map(
-      (task) => CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskType) ? this.canonicalizeCreativeTaskInfo(
-        task,
-        task.taskType,
-        void 0,
-        this.resolveLegacyFormatConverter(this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter)
-      ) : task
+      (task) => assertNativeRequestProposalsTask(
+        CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskType) ? this.canonicalizeCreativeTaskInfo(
+          task,
+          task.taskType,
+          void 0,
+          this.resolveLegacyFormatConverter(
+            this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter
+          )
+        ) : task
+      )
     );
   }
   /**
@@ -4414,12 +4532,15 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    */
   async getTaskInfo(taskId) {
     const task = await this.executor.getTaskInfo(taskId);
-    return task && CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskType) ? this.canonicalizeCreativeTaskInfo(
-      task,
-      task.taskType,
-      void 0,
-      this.resolveLegacyFormatConverter(this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter)
-    ) : task;
+    if (!task) return null;
+    return assertNativeRequestProposalsTask(
+      CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskType) ? this.canonicalizeCreativeTaskInfo(
+        task,
+        task.taskType,
+        void 0,
+        this.resolveLegacyFormatConverter(this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter)
+      ) : task
+    );
   }
   /**
    * Subscribe to task notifications for this agent
@@ -4444,14 +4565,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     return this.executor.onTaskUpdate(
       this.agent.id,
       (task) => callback(
-        CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskType) ? this.canonicalizeCreativeTaskInfo(
-          task,
-          task.taskType,
-          void 0,
-          this.resolveLegacyFormatConverter(
-            this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter
-          )
-        ) : task
+        assertNativeRequestProposalsTask(
+          CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskType) ? this.canonicalizeCreativeTaskInfo(
+            task,
+            task.taskType,
+            void 0,
+            this.resolveLegacyFormatConverter(
+              this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter
+            )
+          ) : task
+        )
       )
     );
   }
@@ -4462,12 +4585,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * @returns Unsubscribe function
    */
   onTaskEvents(callbacks) {
-    const safe = (task) => CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskType) ? this.canonicalizeCreativeTaskInfo(
-      task,
-      task.taskType,
-      void 0,
-      this.resolveLegacyFormatConverter(this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter)
-    ) : task;
+    const safe = (task) => assertNativeRequestProposalsTask(
+      CANONICAL_CREATIVE_ACTIVITY_TASKS.has(task.taskType) ? this.canonicalizeCreativeTaskInfo(
+        task,
+        task.taskType,
+        void 0,
+        this.resolveLegacyFormatConverter(
+          this.canonicalCreativeTaskAssociation(task.taskId)?.legacyFormatConverter
+        )
+      ) : task
+    );
     return this.executor.onTaskEvents(this.agent.id, {
       ...callbacks.onTaskCreated && { onTaskCreated: (task) => callbacks.onTaskCreated(safe(task)) },
       ...callbacks.onTaskUpdated && { onTaskUpdated: (task) => callbacks.onTaskUpdated(safe(task)) },