@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/core/SingleAgentClient.mjs

@@ -6,7 +6,9 @@ const require2 = __adcpCreateRequire(import.meta.url);
 import {
   annotateProductsSupplyPaths
 } from "../supply-path/products.mjs";
-import { randomUUID } from "node:crypto";
+import { randomUUID, scryptSync } from "node:crypto";
+const SKIP_PRODUCT_CACHE = /* @__PURE__ */ Symbol("adcp.skipProductCache");
+const SKIP_ACCOUNT_REGISTRY_OBSERVATION = /* @__PURE__ */ Symbol("adcp.skipAccountRegistryObservation");
 import { ADCP_ENVELOPE_FIELDS } from "../types/adcp.mjs";
 import { parseAdcpMajorVersion, toReleasePrecisionVersion } from "../version.mjs";
 import {
@@ -40,6 +42,7 @@ import {
 import { withTaskDeadline } from "./task-deadline.mjs";
 import { createMCPRequestHeaders } from "../auth/index.mjs";
 import { isAbortOrTimeoutError } from "../protocols/abort.mjs";
+import { getSignedRequestRejection } from "../protocols/signedRequestRejection.mjs";
 import { ProtocolClient, normalizeTransportOptions } from "../protocols/index.mjs";
 import {
   AuthenticationCredentialsRejectedError,
@@ -122,7 +125,16 @@ import {
   assertValidIdempotencyReplayTtlSeconds,
   supportsBuyingMode
 } from "../utils/capabilities.mjs";
-import { AccountPendingApprovalError, AccountRequiredError, UnsupportedBuyingModeError } from "../errors/index.mjs";
+import {
+  AccountPendingApprovalError,
+  AccountRequiredError,
+  AccountNotProvisionedError,
+  AccountNotFoundError,
+  AccountSetupRequiredError,
+  AccountPaymentRequiredError,
+  UnsupportedBuyingModeError
+} from "../errors/index.mjs";
+import { BuyerAccountRegistry } from "./buyer-account-registry.mjs";
 import { sameCountrySet, selectListedAccount } from "./account-resolution.mjs";
 import { normalizeRequestParams } from "../utils/request-normalizer.mjs";
 import { globalAsyncLocalStorage } from "../utils/global-async-local-storage.mjs";
@@ -827,6 +839,8 @@ class SingleAgentClient {
       };
     }
     this.normalizedAgent = this.normalizeAgentConfig(this.agent);
+    if (this.normalizedAgent.oauth_tokens && !this.normalizedAgent.oauth_client_credentials)
+      this.initialOAuthGrantMaterial = JSON.stringify(this.normalizedAgent.oauth_tokens);
     this.capabilityEvidenceAuthMaterial = this.currentCapabilityEvidenceAuthMaterial();
     this.executor = new TaskExecutor({
       workingTimeout: config.workingTimeout || 12e4,
@@ -895,6 +909,179 @@ class SingleAgentClient {
   }
   agent;
   config;
+  _accounts;
+  accountRegistryExplicitlyAccessed = false;
+  initialOAuthGrantMaterial;
+  accountCredentialMaterial;
+  accountCredentialScope;
+  credentialScope(material) {
+    if (this.accountCredentialMaterial !== material) {
+      this.accountCredentialScope = scryptSync(material, "adcp-sdk/account-registry-scope/v1", 32).toString("hex");
+      this.accountCredentialMaterial = material;
+    }
+    return this.accountCredentialScope;
+  }
+  accountScope() {
+    const agent = this.normalizedAgent ?? this.agent;
+    const cc = agent.oauth_client_credentials;
+    if (!cc && agent.oauth_tokens && !this.initialOAuthGrantMaterial)
+      this.initialOAuthGrantMaterial = JSON.stringify(agent.oauth_tokens);
+    const oauthIdentity = cc ? { client_id: cc.client_id, token_endpoint: cc.token_endpoint, scope: cc.scope, resource: cc.resource } : this.initialOAuthGrantMaterial;
+    const signing = agent.request_signing;
+    const signingIdentity = signing ? signing.kind === "provider" ? {
+      keyid: signing.provider.keyid,
+      algorithm: signing.provider.algorithm,
+      fingerprint: signing.provider.fingerprint,
+      purpose: signing.provider.adcpUse
+    } : { keyid: signing.kid, algorithm: signing.alg, key: signing.private_key } : void 0;
+    const credential = this.config.accountRegistryScope ?? this.credentialScope(
+      JSON.stringify({
+        token: agent.auth_token,
+        oauth: oauthIdentity,
+        oauthClient: agent.oauth_client?.client_id,
+        oauthResource: agent.oauth_resource,
+        headers: agent.headers,
+        signing: signingIdentity
+      })
+    );
+    return JSON.stringify([this.agent.agent_uri, this.agent.protocol, credential]);
+  }
+  get accounts() {
+    this.accountRegistryExplicitlyAccessed = true;
+    return this.getAccountRegistry();
+  }
+  getAccountRegistry() {
+    return this._accounts ??= new BuyerAccountRegistry(
+      () => this.accountScope(),
+      async (account, options, taskOptions, dispatch) => {
+        const caps = await this.getCapabilities(taskOptions);
+        const supported = caps.account?.supportedBilling ?? [];
+        const billing = options.billing ?? caps.account?.defaultBilling ?? (supported.length === 1 ? supported[0] : void 0);
+        if (!billing || supported.length && !supported.includes(billing)) {
+          throw new AccountRequiredError(
+            "implicit",
+            "sync_accounts",
+            "Choose a supported billing party before provisioning."
+          );
+        }
+        return this.syncAccounts(
+          {
+            ...dispatch && { idempotency_key: dispatch.idempotencyKey },
+            accounts: [
+              {
+                ...account,
+                billing,
+                ...options.paymentTerms !== void 0 && { payment_terms: options.paymentTerms },
+                ...options.billingEntity !== void 0 && { billing_entity: options.billingEntity }
+              }
+            ]
+          },
+          void 0,
+          { ...taskOptions, [SKIP_ACCOUNT_REGISTRY_OBSERVATION]: true },
+          dispatch
+        );
+      },
+      this.config.accountStorage,
+      async (accountId, options) => {
+        const rows = [];
+        const cursors = /* @__PURE__ */ new Set();
+        let cursor;
+        for (let page = 0; page < 100; page++) {
+          const result = await this.listAccounts(
+            { account: { account_id: accountId }, ...cursor && { pagination: { cursor } } },
+            void 0,
+            { ...options, [SKIP_ACCOUNT_REGISTRY_OBSERVATION]: true }
+          );
+          if (!result.success || result.status !== "completed" || !result.data || !("accounts" in result.data))
+            throw new Error("Account status reconciliation failed.");
+          rows.push(...result.data.accounts);
+          if (rows.some((row) => row.account_id === accountId) || !result.data.pagination?.has_more)
+            return rows.filter((row) => row.account_id === accountId);
+          const next = result.data.pagination.cursor;
+          if (!next || cursors.has(next)) break;
+          cursors.add(next);
+          cursor = next;
+        }
+        throw new Error("Account status reconciliation could not complete pagination.");
+      },
+      {
+        ...this.config.accountRegistryOptions,
+        provisionOwnsDispatchBoundary: true,
+        maxEntries: this.config.accountRegistryMaxEntries,
+        normalizeOptions: async (options, taskOptions) => {
+          if (options.billing) return options;
+          const caps = await this.getCapabilities(taskOptions);
+          const supported = caps.account?.supportedBilling ?? [];
+          const billing = caps.account?.defaultBilling ?? (supported.length === 1 ? supported[0] : void 0);
+          return { ...options, ...billing && { billing } };
+        }
+      }
+    );
+  }
+  /**
+   * The memoized registry backs `resolveAccount()` only when the caller opts
+   * in with an account policy or registry configuration. Otherwise
+   * `resolveAccount()` keeps the SDK 14.0 sync-on-every-call behavior.
+   */
+  accountRegistryOptedIn() {
+    return (this.config.accountPolicy ?? "off") !== "off" || this.config.accountStorage !== void 0 || this.config.accountRegistryScope !== void 0 || this.config.accountRegistryMaxEntries !== void 0 || this.config.accountRegistryOptions !== void 0;
+  }
+  accountRegistryContext(task, params, options) {
+    const knownOnly = !this.accountRegistryExplicitlyAccessed && (this.config.accountPolicy ?? "off") === "off" && !this.config.accountStorage;
+    if (knownOnly && !this._accounts) return void 0;
+    if (options?.[SKIP_ACCOUNT_REGISTRY_OBSERVATION])
+      return void 0;
+    if (task !== "sync_accounts" && task !== "list_accounts") return void 0;
+    return {
+      scope: this.accountScope(),
+      ...knownOnly && { knownOnly: true },
+      observationEpoch: this.getAccountRegistry().captureObservation(),
+      ...task === "list_accounts" && params.account && { refs: [params.account] },
+      ...task === "sync_accounts" && {
+        refs: Array.isArray(params.accounts) ? params.accounts.flatMap((value) => {
+          const ref = canonicalAccountRoutingSnapshot(value);
+          return ref ? [ref] : [];
+        }) : [],
+        dryRun: params.dry_run === true
+      }
+    };
+  }
+  async applyAccountPolicy(task, params, options) {
+    const policy = this.config.accountPolicy ?? "off";
+    const ref = params?.account ?? (typeof params?.account_id === "string" ? { account_id: params.account_id } : void 0);
+    if (policy === "off" || options?.skipAccountValidation || options?.preserveGovernedPayload || !ref || task === "list_accounts")
+      return params;
+    if (typeof ref !== "object" || ref === null || !("account_id" in ref) && (typeof ref.brand?.domain !== "string" || typeof ref.operator !== "string"))
+      return params;
+    const known = await this.getAccountRegistry().get(ref);
+    if (known && !["unknown", "provisioning", "failed_provisioning"].includes(known.status)) {
+      if (["create_media_buy", "buy_products", "accept_proposal", "activate_signal", "acquire_rights"].includes(task) && known.status !== "active") {
+        if (known.status === "pending_approval") throw new AccountPendingApprovalError(ref, known.account_id);
+        if (known.status === "payment_required") throw new AccountPaymentRequiredError();
+        throw new AccountSetupRequiredError(
+          `Account status is ${known.status}. Refresh it with client.accounts.applyStatusChange or complete seller setup.`
+        );
+      }
+      return params;
+    }
+    if (policy === "strict" || ![
+      "get_products",
+      "list_products",
+      "get_signals",
+      "request_proposals",
+      "refine_proposals",
+      "decline_proposals"
+    ].includes(task)) {
+      throw new AccountNotProvisionedError(ref, task);
+    }
+    const caps = await this.getCapabilities(options);
+    if (caps._synthetic || ["get_products", "list_products"].includes(task) && caps.account?.requiredForProducts || params.push_notification_config || !schemaAllowsTopLevelField(task, "brand")) {
+      throw new AccountNotProvisionedError(ref, task);
+    }
+    if (!("brand" in ref)) throw new AccountNotProvisionedError(ref, task);
+    const { account, ...publicRequest } = params;
+    return { ...publicRequest, brand: params.brand ?? ref.brand };
+  }
   executor;
   asyncHandler;
   normalizedAgent;
@@ -1061,6 +1248,7 @@ class SingleAgentClient {
     } = configuredResolverOptions ?? {};
     const resolver = new ResolvedAgentJwksResolver(registration.agentUrl, registration.protocol, {
       ...resolverOptionsWithoutOperatorContext,
+      legacyWebhookFallback: configuredResolverOptions?.legacyWebhookFallback ?? true,
       ...delegatedOperatorAuthorization?.brand !== void 0 && {
         requiredOperatorBrand: delegatedOperatorAuthorization.brand
       },
@@ -1828,6 +2016,8 @@ class SingleAgentClient {
         }
         return { success: true };
       } catch (error) {
+        const signedRejection = getSignedRequestRejection(error);
+        if (signedRejection) throw signedRejection;
         if (isAbortOrTimeoutError(error)) {
           throw error;
         }
@@ -2140,6 +2330,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           },
           {
             jwks: this.webhookJwksFor(registration),
+            publisherPins: await this.config.webhookVerification?.publisherPins?.(registration),
+            onKeyResolutionError: this.config.webhookVerification?.onKeyResolutionError,
             replayStore: this.webhookReplayStore,
             revocationStore: this.webhookRevocationStore,
             ...this.config.webhookVerification?.now && { now: this.config.webhookVerification.now },
@@ -2151,6 +2343,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         );
       } catch (cause) {
         if (cause instanceof WebhookSignatureError) {
+          if (cause.retryable)
+            return {
+              ok: false,
+              code: "webhook_verification_unavailable",
+              message: "Seller signing keys could not be resolved for webhook verification.",
+              cause
+            };
           return { ok: false, code: cause.code, message: cause.message, cause };
         }
         if (cause instanceof AgentResolverError && RequestSigningErrorCodeMetadata[cause.code].recovery !== "transient") {
@@ -2972,6 +3171,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   async executeAndHandleWithinDeadline(taskType, handlerName, params, inputHandler, options, transformCompletedResponse, legacyFormatConverter, canonicalRequest, projectionCatalogs) {
     throwIfAborted(options?.signal);
     const canonicalCreativeInvocation = CANONICAL_CREATIVE_ACTIVITY_TASKS.has(taskType) || canonicalRequest !== void 0;
+    params = await this.applyAccountPolicy(taskType, params, options);
     let normalizedParams = options?.preserveGovernedPayload ? params : normalizeRequestParams(taskType, params, {
       skipIdempotencyAutoInject: options?.skipIdempotencyAutoInject,
       skipAccountValidation: options?.skipAccountValidation
@@ -3055,6 +3255,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         serverVersionSynthetic: capabilityDiscoveryContext.capabilities._synthetic
       },
       productPolicyRequest: productPolicyRequestSnapshot(normalizedParams),
+      accountRegistry: this.accountRegistryContext(taskType, normalizedParams, effectiveOptions),
       ...projectionCatalogs !== void 0 && { projectionCatalogs },
       ...routingSnapshot !== void 0 && { routingSnapshot },
       ...effectiveOptions?.taskId !== void 0 && { optionTaskId: effectiveOptions.taskId },
@@ -3119,6 +3320,53 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     const completionHandlerAlreadyPublished = hasCompletionHandlerAlreadyPublished(result);
     const settlementAcknowledger = result[DEFERRED_SETTLEMENT_ACK];
     const taskType = context.taskType;
+    if (context.accountRegistry !== void 0 && context.accountRegistry.scope === this.accountScope() && result.success && result.status === "completed" && result.data && typeof result.data === "object" && "accounts" in result.data && Array.isArray(result.data.accounts)) {
+      try {
+        const registry = this.getAccountRegistry();
+        let refs = context.accountRegistry.refs ?? [];
+        let rows = result.data.accounts;
+        if (context.accountRegistry.knownOnly) {
+          refs = (await Promise.all(refs.map(async (ref) => await registry.get(ref) ? ref : void 0))).filter(
+            (ref) => ref !== void 0
+          );
+          if (taskType === "list_accounts") {
+            rows = (await Promise.all(
+              result.data.accounts.map(async (row) => {
+                const ref = canonicalAccountRoutingSnapshot(row);
+                if (ref && await registry.get(ref)) return row;
+                const natural = canonicalAccountRoutingSnapshot({ ...row, account_id: void 0 });
+                return natural && await registry.get(natural) ? row : void 0;
+              })
+            )).filter((row) => row !== void 0);
+          }
+        }
+        if (context.accountRegistry.scope !== this.accountScope()) return result;
+        if (taskType === "sync_accounts")
+          await registry.observeSync(
+            refs,
+            rows,
+            context.accountRegistry.dryRun,
+            context.accountRegistry.observationEpoch
+          );
+        if (taskType === "list_accounts") {
+          const ref = refs[0];
+          await registry.observeList(
+            rows,
+            ref && "account_id" in ref && (!result.data.pagination?.has_more || result.data.accounts.some((row) => row.account_id === ref.account_id)) ? ref.account_id : void 0,
+            context.accountRegistry.observationEpoch
+          );
+        }
+      } catch {
+        result.debug_logs = [
+          ...result.debug_logs ?? [],
+          {
+            level: "warn",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            message: "Account registry observation failed. The seller operation completed; reconcile with listAccounts before relying on the registry."
+          }
+        ];
+      }
+    }
     const resumedOptions = {
       ...options ?? {},
       ...context.optionTaskId !== void 0 && { taskId: context.optionTaskId },
@@ -4138,7 +4386,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     );
     return withTaskDeadline(snapshotTaskOptions(taskOptions), async (effectiveOptions) => {
       this.assertRequestSupportedByConfiguredVersion("get_products", params, effectiveOptions);
-      let request = params;
+      let request = await this.applyAccountPolicy("get_products", params, effectiveOptions);
       const legacyAccountId = request.account_id;
       const accountReference = request.account ?? (typeof legacyAccountId === "string" && legacyAccountId ? { account_id: legacyAccountId } : void 0);
       if (!request.account && typeof legacyAccountId === "string" && legacyAccountId) {
@@ -4175,10 +4423,36 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         request = { ...request, buying_mode: "wholesale" };
       }
       const account = canonicalAccountRoutingSnapshot(accountReference);
-      return this.executeAndHandle(
+      const cache = !effectiveOptions.skipRequestValidation && !effectiveOptions.preserveGovernedPayload && !inputHandler && !request.push_notification_config && !this.config.webhookUrlTemplate && !this.config.handlers?.onGetProductsStatusChange ? this.config.productCache : void 0;
+      const cacheScope = cache ? JSON.stringify([
+        this.accountScope(),
+        this.resolvedAdcpVersion,
+        this.capabilityEvidenceScopeKey,
+        effectiveOptions.contextId
+      ]) : "";
+      const cacheParams = request;
+      const skipCacheRead = options?.[SKIP_PRODUCT_CACHE];
+      if (cache && !skipCacheRead && cacheParams.if_wholesale_feed_version === void 0 && cacheParams.if_pricing_version === void 0) {
+        const hit = cache.read(cacheScope, cacheParams);
+        if (hit) {
+          throwIfAborted(effectiveOptions.signal);
+          if (hit.success && hit.status === "completed")
+            this.rememberCanonicalProductRoutes(hit.data.products ?? [], account, hit.data.products ?? []);
+          return attachMatch(
+            await this.applyProductPropertyPolicy(
+              hit,
+              "get_products",
+              productPolicyRequestSnapshot(request),
+              effectiveOptions.signal
+            )
+          );
+        }
+      }
+      const conditionalSnapshot = skipCacheRead ? void 0 : cache?.read(cacheScope, cacheParams, true);
+      const result = await this.executeAndHandle(
         "get_products",
         "onGetProductsStatusChange",
-        request,
+        cache && !skipCacheRead ? cache.conditionalParams(cacheScope, cacheParams) : request,
         inputHandler,
         effectiveOptions,
         (data) => {
@@ -4196,6 +4470,37 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         void 0,
         projectionCatalogs
       );
+      const finishCache = async (completed) => {
+        if (!cache) return completed;
+        const cachedResult = cache.write(cacheScope, cacheParams, completed, conditionalSnapshot);
+        if (cachedResult.success && cachedResult.status === "completed") {
+          if (!skipCacheRead && cacheParams.if_wholesale_feed_version === void 0 && cacheParams.if_pricing_version === void 0 && cachedResult.data.unchanged === true) {
+            return this.getProducts(params, inputHandler, {
+              ...options,
+              ...effectiveOptions,
+              [SKIP_PRODUCT_CACHE]: true
+            });
+          }
+          this.rememberCanonicalProductRoutes(
+            cachedResult.data.products ?? [],
+            account,
+            cachedResult.data.products ?? []
+          );
+        }
+        if (cachedResult.submitted) {
+          const submitted = cachedResult.submitted;
+          cachedResult.submitted = {
+            ...submitted,
+            waitForCompletion: (interval, signal) => submitted.waitForCompletion(interval, signal).then(finishCache)
+          };
+        }
+        if (cachedResult.deferred) {
+          const deferred = cachedResult.deferred;
+          cachedResult.deferred = { ...deferred, resume: (input) => deferred.resume(input).then(finishCache) };
+        }
+        return attachMatch(cachedResult);
+      };
+      return finishCache(result);
     });
   }
   /** Discover products through the compact AdCP 3.2 catalog task. */
@@ -4934,7 +5239,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         const seenCursors = /* @__PURE__ */ new Set();
         let cursor;
         for (let page = 0; page < 100; page++) {
-          const result2 = await this.listAccounts(
+          const result = await this.listAccounts(
             {
               status: "active",
               sandbox: hints.sandbox ?? false,
@@ -4943,13 +5248,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             void 0,
             effectiveOptions
           );
-          onTaskResult?.(result2);
-          if (!result2.success || result2.status !== "completed" || !result2.data || !("accounts" in result2.data) || !Array.isArray(result2.data.accounts)) {
+          onTaskResult?.(result);
+          if (!result.success || result.status !== "completed" || !result.data || !("accounts" in result.data) || !Array.isArray(result.data.accounts)) {
             throw new Error("list_accounts did not return a completed account list.");
           }
-          accounts.push(...result2.data.accounts);
-          if (!result2.data.pagination?.has_more) return selectListedAccount(accounts, hints);
-          const nextCursor = result2.data.pagination.cursor;
+          accounts.push(...result.data.accounts);
+          if (!result.data.pagination?.has_more) return selectListedAccount(accounts, hints);
+          const nextCursor = result.data.pagination.cursor;
           if (!nextCursor || seenCursors.has(nextCursor)) break;
           seenCursors.add(nextCursor);
           cursor = nextCursor;
@@ -5016,42 +5321,84 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           `Choose a supported billing party for sync_accounts (seller supports: ${supportedBilling.join(", ") || "(none)"}).`
         );
       }
-      const result = await this.syncAccounts(
-        {
-          accounts: [
-            {
-              ...account,
-              billing
-            }
-          ]
-        },
-        void 0,
-        effectiveOptions
-      );
-      onTaskResult?.(result);
-      if (!result.success || result.status !== "completed" || !result.data || !("accounts" in result.data) || !Array.isArray(result.data.accounts)) {
-        throw new Error("sync_accounts did not return a completed account result.");
-      }
-      const synced = result.data.accounts.find(
-        (row) => row.brand?.domain === hints.brand.domain && row.operator === hints.operator && (!hints.brand.brand_id || row.brand.brand_id === hints.brand.brand_id) && sameCountrySet(hints.brand.countries, row.brand.countries) && (!hints.operatorUnit || row.operator_unit?.id === hints.operatorUnit.id) && (!hints.currency || row.currency === hints.currency) && (!hints.timezone || row.timezone === hints.timezone) && (row.sandbox === void 0 || row.sandbox === true === (hints.sandbox === true))
-      );
-      if (synced?.status === "pending_approval") {
-        throw new AccountPendingApprovalError(account, synced.account_id);
+      if (!this.accountRegistryOptedIn()) {
+        const result = await this.syncAccounts(
+          {
+            accounts: [
+              {
+                ...account,
+                billing,
+                ...hints.paymentTerms !== void 0 && { payment_terms: hints.paymentTerms },
+                ...hints.billingEntity !== void 0 && { billing_entity: hints.billingEntity }
+              }
+            ]
+          },
+          void 0,
+          effectiveOptions
+        );
+        onTaskResult?.(result);
+        if (!result.success || result.status !== "completed" || !result.data || !("accounts" in result.data) || !Array.isArray(result.data.accounts)) {
+          throw new Error("sync_accounts did not return a completed account result.");
+        }
+        const syncedRow = result.data.accounts.find(
+          (row) => row.brand?.domain === hints.brand.domain && row.operator === hints.operator && (!hints.brand.brand_id || row.brand.brand_id === hints.brand.brand_id) && sameCountrySet(hints.brand.countries, row.brand.countries) && (!hints.operatorUnit || row.operator_unit?.id === hints.operatorUnit.id) && (!hints.currency || row.currency === hints.currency) && (!hints.timezone || row.timezone === hints.timezone) && (row.sandbox === void 0 || row.sandbox === true === (hints.sandbox === true))
+        );
+        if (syncedRow?.status === "pending_approval") {
+          throw new AccountPendingApprovalError(account, syncedRow.account_id);
+        }
+        if (!syncedRow || syncedRow.action === "failed" || syncedRow.status !== "active") {
+          throw new AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "sync_accounts did not establish an active account for the requested brand and operator."
+          );
+        }
+        return account;
       }
-      if (!synced || synced.action === "failed" || synced.status !== "active") {
-        throw new AccountRequiredError(
-          "implicit",
-          "resolveAccount",
-          "sync_accounts did not establish an active account for the requested brand and operator."
+      let synced;
+      try {
+        synced = await this.getAccountRegistry().ensure(
+          account,
+          {
+            billing,
+            paymentTerms: hints.paymentTerms,
+            billingEntity: hints.billingEntity
+          },
+          effectiveOptions,
+          onTaskResult
         );
+      } catch (error) {
+        if (error instanceof AccountNotFoundError)
+          throw new AccountRequiredError("implicit", "resolveAccount", error.message);
+        throw error;
       }
+      if (synced.status === "pending_approval") throw new AccountPendingApprovalError(account, synced.account_id);
+      if (synced.status !== "active")
+        throw new AccountRequiredError("implicit", "resolveAccount", "The account is not active.");
       return account;
     });
   }
   /**
    * Sync accounts
    */
-  async syncAccounts(params, inputHandler, options) {
+  async syncAccounts(params, inputHandler, options, dispatch) {
+    if (dispatch)
+      return this.executeTaskUnprojected(
+        "sync_accounts",
+        params,
+        inputHandler,
+        options,
+        "onSyncAccountsStatusChange",
+        Object.assign(
+          async (effectiveParams) => {
+            if (dispatch.requireIdempotencyKey !== false && effectiveParams.idempotency_key !== dispatch.idempotencyKey)
+              throw new ConfigurationError("Account provisioning idempotency key changed before dispatch.");
+            await dispatch.beforeDispatch();
+            return { action: "dispatch_ready" };
+          },
+          { terminalSettlement: "executor" }
+        )
+      );
     return this.executeAndHandle(
       "sync_accounts",
       "onSyncAccountsStatusChange",
@@ -5315,6 +5662,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     const startTime = Date.now();
     let detectedServerVersion;
     let detectedServerVersionSynthetic;
+    params = await this.applyAccountPolicy(taskName, params, options);
     try {
       const normalizedParams = options?.preserveGovernedPayload ? params : normalizeRequestParams(taskName, params, {
         skipIdempotencyAutoInject: options?.skipIdempotencyAutoInject,
@@ -5380,6 +5728,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           serverVersionSynthetic: capabilityDiscoveryContext.capabilities._synthetic
         },
         productPolicyRequest: productPolicyRequestSnapshot(normalizedParams),
+        accountRegistry: this.accountRegistryContext(taskName, normalizedParams, effectiveOptions),
         ...effectiveOptions?.taskId !== void 0 && { optionTaskId: effectiveOptions.taskId },
         ...effectiveOptions?.contextId !== void 0 && { optionContextId: effectiveOptions.contextId }
       };

package/dist/lib/core/TaskExecutor.d.mts

@@ -41,6 +41,8 @@ export declare function acknowledgeDeferredSettlement(result: TaskResult<any>):
 export declare function rejectDeferredSettlement(result: TaskResult<any>): Promise<void>;
 /** Supporting contract for the internal pre-dispatch boundary. */
 export type BeforeProtocolDispatchHookResult<T> = {
+    action: 'dispatch_ready';
+} | {
     action: 'dispatch_committed';
     /** Require the owning durable coordinator to authorize every seller-input continuation. */
     requireDeferredSettlementResumeAuthorization?: boolean;
@@ -84,7 +86,7 @@ export interface ExternalTaskStatusResult {
     error?: string;
 }
 /** Hook used by higher-level SDK coordinators at the final dispatch boundary. */
-export type BeforeProtocolDispatchHook<T> = (effectiveParams: any, context: BeforeProtocolDispatchContext) => Promise<BeforeProtocolDispatchHookResult<T>>;
+export type BeforeProtocolDispatchHook<T> = ((effectiveParams: any, context: BeforeProtocolDispatchContext) => Promise<BeforeProtocolDispatchHookResult<T>>) & {};
 /**
  * Webhook manager for submitted tasks
  */

package/dist/lib/core/TaskExecutor.d.ts

@@ -41,6 +41,8 @@ export declare function acknowledgeDeferredSettlement(result: TaskResult<any>):
 export declare function rejectDeferredSettlement(result: TaskResult<any>): Promise<void>;
 /** Supporting contract for the internal pre-dispatch boundary. */
 export type BeforeProtocolDispatchHookResult<T> = {
+    action: 'dispatch_ready';
+} | {
     action: 'dispatch_committed';
     /** Require the owning durable coordinator to authorize every seller-input continuation. */
     requireDeferredSettlementResumeAuthorization?: boolean;
@@ -84,7 +86,7 @@ export interface ExternalTaskStatusResult {
     error?: string;
 }
 /** Hook used by higher-level SDK coordinators at the final dispatch boundary. */
-export type BeforeProtocolDispatchHook<T> = (effectiveParams: any, context: BeforeProtocolDispatchContext) => Promise<BeforeProtocolDispatchHookResult<T>>;
+export type BeforeProtocolDispatchHook<T> = ((effectiveParams: any, context: BeforeProtocolDispatchContext) => Promise<BeforeProtocolDispatchHookResult<T>>) & {};
 /**
  * Webhook manager for submitted tasks
  */