@adcp/sdk 14.0.0-rc.37 → 14.0.0-rc.39

package/dist/lib/core/TaskExecutor.mjs

@@ -1,4 +1,4 @@
-import { createHmac, randomBytes, randomUUID } from "crypto";
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "crypto";
 import {
   ProtocolClient,
   normalizeTransportOptions,
@@ -76,6 +76,14 @@ class DeferredSettlementOwnershipError extends Error {
     this.name = "DeferredSettlementOwnershipError";
   }
 }
+class DirectContinuationRecoveryError extends DeferredSettlementOwnershipError {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "DirectContinuationRecoveryError";
+  }
+  reason;
+}
 function transferDeferredSettlementAcknowledgement(source, target) {
   for (const symbol of [DEFERRED_SETTLEMENT_ACK, DEFERRED_SETTLEMENT_NACK]) {
     const descriptor = Object.getOwnPropertyDescriptor(source, symbol);
@@ -349,9 +357,63 @@ function snapshotTaskOptions(options) {
     ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) },
     ...options.delegatedOperatorAuthorization !== void 0 && {
       delegatedOperatorAuthorization: { ...options.delegatedOperatorAuthorization }
+    },
+    ...options.durableContinuationRecovery !== void 0 && {
+      durableContinuationRecovery: { ...options.durableContinuationRecovery }
     }
   };
 }
+const DIRECT_CONTINUATION_RECOVERY_KEY_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const MAX_DIRECT_CONTINUATION_OWNER_SCOPE_BYTES = 1024;
+function directContinuationRecoveryDigest(key) {
+  return createHash("sha256").update(key, "utf8").digest("base64url");
+}
+function directContinuationDigestMatches(expectedDigest, actualDigest) {
+  try {
+    const expected = Buffer.from(expectedDigest, "base64url");
+    const actual = Buffer.from(actualDigest, "base64url");
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+  } catch {
+    return false;
+  }
+}
+function directContinuationRecoveryKeyMatches(expectedDigest, recoveryKey) {
+  return directContinuationDigestMatches(expectedDigest, directContinuationRecoveryDigest(recoveryKey));
+}
+function assertDirectContinuationOwnerScope(ownerScope) {
+  if (typeof ownerScope !== "string" || ownerScope.trim().length === 0 || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(ownerScope) || Buffer.byteLength(ownerScope, "utf8") > MAX_DIRECT_CONTINUATION_OWNER_SCOPE_BYTES) {
+    throw new ConfigurationError(
+      "durableContinuationRecovery.ownerScope must be a non-empty authenticated owner/account scope of at most 1024 UTF-8 bytes."
+    );
+  }
+}
+function directContinuationSellerOrigin(agent) {
+  let sellerOrigin = agent.agent_uri;
+  try {
+    sellerOrigin = new URL(agent.agent_uri).origin;
+  } catch {
+  }
+  return sellerOrigin;
+}
+function directContinuationOwnerBindingDigest(agent, ownerScope) {
+  return directContinuationRecoveryDigest(
+    canonicalize({
+      ownerScope,
+      seller: { id: agent.id, origin: directContinuationSellerOrigin(agent), protocol: agent.protocol }
+    })
+  );
+}
+function directContinuationRecoveryDenied() {
+  return new DirectContinuationRecoveryError("Direct continuation recovery is not authorized.", "not_authorized");
+}
+function attachDirectContinuationRecovery(result, recovery) {
+  const deferred = result.deferred;
+  if (!deferred) return result;
+  const resume = deferred.resume;
+  deferred.recovery = { ...recovery };
+  deferred.resume = async (input) => attachDirectContinuationRecovery(await resume(input), recovery);
+  return result;
+}
 function snapshotTransportOptions(transport) {
   return transport === void 0 ? void 0 : { ...transport };
 }
@@ -682,6 +744,19 @@ class TaskExecutor {
     const effectiveServerVersion = serverVersion ?? "v3";
     this.lastKnownServerVersion = effectiveServerVersion;
     params = structuredClone(params);
+    if (options.durableContinuationRecovery !== void 0) {
+      assertDirectContinuationOwnerScope(options.durableContinuationRecovery.ownerScope);
+      if (agent.protocol !== "a2a") {
+        throw new ConfigurationError("durableContinuationRecovery is supported only for resumable A2A mutations.");
+      }
+      if (!requestUsesIdempotency(taskName, params)) {
+        throw new ConfigurationError("durableContinuationRecovery is supported only for mutating AdCP requests.");
+      }
+      if (!this.config.deferredStorage) {
+        throw new ConfigurationError("durableContinuationRecovery requires deferredStorage.");
+      }
+      this.requireDeferredSettlementOperationRouting(this.config.deferredStorage, true);
+    }
     const taskId = getTaskOperationId(options) ?? randomUUID();
     const startTime = Date.now();
     const workingTimeout = this.config.workingTimeout || 12e4;
@@ -1771,7 +1846,9 @@ class TaskExecutor {
     const inputRequest = this.responseParser.parseInputRequest(response);
     const serverContextId = this.responseParser.getContextId(response) ?? response.contextId;
     const a2aTaskId = this.responseParser.getA2AContinuationTaskId(response);
-    const settlementServerTaskId = deferTerminalTaskStatus ? this.responseParser.getTaskId(response) : void 0;
+    const directContinuationRecovery = !deferTerminalTaskStatus && options.durableContinuationRecovery !== void 0;
+    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 metadata = this.buildMetadata({
@@ -1808,6 +1885,7 @@ class TaskExecutor {
       const token = randomUUID();
       const deferredStorage = this.config.deferredStorage;
       const usesDurableStorage = deferredStorage !== void 0 && persistPausedContinuation;
+      const directRecoveryKey = directContinuationRecovery && usesDurableStorage ? randomBytes(32).toString("base64url") : void 0;
       if (usesDurableStorage) {
         const createdAt = Date.now();
         const ttlSeconds = this.config.deferredTaskTtlSeconds ?? DEFAULT_DEFERRED_TASK_TTL_SECONDS;
@@ -1831,10 +1909,18 @@ class TaskExecutor {
           ...deferredClientContext !== void 0 && {
             clientContext: durableDeferredSnapshot(deferredClientContext)
           },
-          ...deferTerminalTaskStatus && {
+          ...operationRoutedContinuation && {
             settlementOperationId: taskId,
             settlementOperationRouteRequired: true
           },
+          ...directContinuationRecovery && {
+            directContinuationRecovery: true,
+            directContinuationRecoveryKeyDigest: directContinuationRecoveryDigest(directRecoveryKey),
+            directContinuationOwnerBindingDigest: directContinuationOwnerBindingDigest(
+              agent,
+              options.durableContinuationRecovery.ownerScope
+            )
+          },
           ...deferTerminalTaskStatus && requireDeferredSettlementResumeAuthorization && {
             settlementResumeAuthorizationRequired: true
           },
@@ -1842,8 +1928,10 @@ class TaskExecutor {
           createdAt,
           expiresAt: createdAt + ttlSeconds * 1e3
         };
-        if (deferTerminalTaskStatus) this.requireDeferredSettlementOperationRouting(deferredStorage);
-        const stored = deferTerminalTaskStatus ? await deferredStorage.putForSettlementOperationIfAbsent(taskId, token, deferredState, ttlSeconds) : await deferredStorage.putIfAbsent(token, deferredState, ttlSeconds);
+        if (operationRoutedContinuation) {
+          this.requireDeferredSettlementOperationRouting(deferredStorage, directContinuationRecovery);
+        }
+        const stored = operationRoutedContinuation ? await deferredStorage.putForSettlementOperationIfAbsent(taskId, token, deferredState, ttlSeconds) : await deferredStorage.putIfAbsent(token, deferredState, ttlSeconds);
         if (!stored) {
           throw new Error("Deferred continuation token already exists; refusing to replace another task.");
         }
@@ -1884,6 +1972,12 @@ class TaskExecutor {
         question: inputRequest.question,
         resume: usesDurableStorage ? (input) => this.resumeDeferredTaskFromLiveClosure(token, input, !deferTerminalTaskStatus) : resumeInProcess
       };
+      if (directRecoveryKey !== void 0) {
+        const recovery = { operationId: taskId, recoveryKey: directRecoveryKey };
+        deferred.recovery = recovery;
+        const resume = deferred.resume;
+        deferred.resume = async (input) => attachDirectContinuationRecovery(await resume(input), recovery);
+      }
       return {
         success: true,
         // The task is progressing, not failed
@@ -1932,6 +2026,7 @@ class TaskExecutor {
       const token = handlerResponse.token;
       const deferredStorage = this.config.deferredStorage;
       const usesDurableStorage = deferredStorage !== void 0 && persistPausedContinuation;
+      const directRecoveryKey = directContinuationRecovery && usesDurableStorage ? randomBytes(32).toString("base64url") : void 0;
       if (usesDurableStorage) {
         assertDeferredContinuationToken(token);
         const createdAt = Date.now();
@@ -1956,10 +2051,18 @@ class TaskExecutor {
           ...deferredClientContext !== void 0 && {
             clientContext: durableDeferredSnapshot(deferredClientContext)
           },
-          ...deferTerminalTaskStatus && {
+          ...operationRoutedContinuation && {
             settlementOperationId: taskId,
             settlementOperationRouteRequired: true
           },
+          ...directContinuationRecovery && {
+            directContinuationRecovery: true,
+            directContinuationRecoveryKeyDigest: directContinuationRecoveryDigest(directRecoveryKey),
+            directContinuationOwnerBindingDigest: directContinuationOwnerBindingDigest(
+              agent,
+              options.durableContinuationRecovery.ownerScope
+            )
+          },
           ...deferTerminalTaskStatus && requireDeferredSettlementResumeAuthorization && {
             settlementResumeAuthorizationRequired: true
           },
@@ -1967,8 +2070,10 @@ class TaskExecutor {
           createdAt,
           expiresAt: createdAt + ttlSeconds * 1e3
         };
-        if (deferTerminalTaskStatus) this.requireDeferredSettlementOperationRouting(deferredStorage);
-        const stored = deferTerminalTaskStatus ? await deferredStorage.putForSettlementOperationIfAbsent(taskId, token, deferredState, ttlSeconds) : await deferredStorage.putIfAbsent(token, deferredState, ttlSeconds);
+        if (operationRoutedContinuation) {
+          this.requireDeferredSettlementOperationRouting(deferredStorage, directContinuationRecovery);
+        }
+        const stored = operationRoutedContinuation ? await deferredStorage.putForSettlementOperationIfAbsent(taskId, token, deferredState, ttlSeconds) : await deferredStorage.putIfAbsent(token, deferredState, ttlSeconds);
         if (!stored) {
           throw new Error("Deferred continuation token already exists; refusing to replace another task.");
         }
@@ -2010,6 +2115,12 @@ class TaskExecutor {
         question: inputRequest.question,
         resume: usesDurableStorage ? (input) => this.resumeDeferredTaskFromLiveClosure(token, input, !deferTerminalTaskStatus) : resumeInProcess
       };
+      if (directRecoveryKey !== void 0) {
+        const recovery = { operationId: taskId, recoveryKey: directRecoveryKey };
+        deferred.recovery = recovery;
+        const resume = deferred.resume;
+        deferred.resume = async (input) => attachDirectContinuationRecovery(await resume(input), recovery);
+      }
       return {
         success: true,
         // The task is progressing, not failed
@@ -2374,10 +2485,10 @@ class TaskExecutor {
     assertDeferredContinuationToken(token);
     return await this.config.deferredStorage.has(token) === true;
   }
-  requireDeferredSettlementOperationRouting(storage) {
+  requireDeferredSettlementOperationRouting(storage, direct = false) {
     if (typeof storage.putForSettlementOperationIfAbsent !== "function" || typeof storage.getBySettlementOperationId !== "function" || typeof storage.replaceForSettlementOperationIfVersion !== "function") {
       throw new ConfigurationError(
-        "Committed deferred settlement requires atomic operation routing so paused mutations remain discoverable across crashes. Use MemoryStorage or implement the DeferredTaskStorage operation-route contract."
+        direct ? "durableContinuationRecovery requires atomic DeferredTaskStorage operation routing. Use MemoryStorage or implement putForSettlementOperationIfAbsent(), getBySettlementOperationId(), and replaceForSettlementOperationIfVersion()." : "Committed deferred settlement requires atomic operation routing so paused mutations remain discoverable across crashes. Use MemoryStorage or implement the DeferredTaskStorage operation-route contract."
       );
     }
   }
@@ -2395,7 +2506,7 @@ class TaskExecutor {
     if (state.settlementOperationId === void 0 || state.settlementOperationRouteRequired !== true) {
       return storage.replaceIfVersion(token, expectedVersion, state, ttlSeconds);
     }
-    this.requireDeferredSettlementOperationRouting(storage);
+    this.requireDeferredSettlementOperationRouting(storage, state.directContinuationRecovery === true);
     return storage.replaceForSettlementOperationIfVersion(
       state.settlementOperationId,
       token,
@@ -2428,8 +2539,58 @@ class TaskExecutor {
     }
     const routed = await this.loadDeferredSettlementOperationRoute(storage, operationId);
     if (!routed) return void 0;
+    if (routed.state.directContinuationRecovery === true) {
+      throw new DeferredSettlementOwnershipError(
+        "A direct continuation route cannot be recovered through committed settlement authorization."
+      );
+    }
     return this.recoverRoutedDeferredTask(operationId, routed, publishTerminalTaskStatus);
   }
+  /** Recover an opt-in direct continuation through its secret operation capability. */
+  async recoverDirectPauseContinuation(request, publishTerminalTaskStatus = true) {
+    const storage = this.config.deferredStorage;
+    if (!storage) throw new ConfigurationError("Direct continuation recovery requires deferredStorage.");
+    this.requireDeferredSettlementOperationRouting(storage, true);
+    const operationId = typeof request?.operationId === "string" ? request.operationId : "";
+    const recoveryKey = typeof request?.recoveryKey === "string" ? request.recoveryKey : "";
+    const ownerScope = typeof request?.ownerScope === "string" ? request.ownerScope : "";
+    if (!operationId || !DIRECT_CONTINUATION_RECOVERY_KEY_PATTERN.test(recoveryKey) || ownerScope.trim().length === 0 || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(ownerScope) || Buffer.byteLength(ownerScope, "utf8") > MAX_DIRECT_CONTINUATION_OWNER_SCOPE_BYTES) {
+      throw directContinuationRecoveryDenied();
+    }
+    const routed = await this.loadDeferredSettlementOperationRoute(storage, operationId);
+    const digest = routed?.state.directContinuationRecoveryKeyDigest;
+    if (!routed || routed.state.directContinuationRecovery !== true || typeof digest !== "string" || !directContinuationRecoveryKeyMatches(digest, recoveryKey)) {
+      throw directContinuationRecoveryDenied();
+    }
+    let agent;
+    try {
+      agent = this.deferredAgents.get(routed.state.agentId) ?? await this.config.resolveDeferredAgent?.(routed.state.agentId);
+    } catch {
+      throw directContinuationRecoveryDenied();
+    }
+    const expectedOwnerBinding = routed.state.directContinuationOwnerBindingDigest;
+    if (!agent || agent.id !== routed.state.agentId || agent.protocol !== "a2a" || typeof expectedOwnerBinding !== "string" || !directContinuationDigestMatches(expectedOwnerBinding, directContinuationOwnerBindingDigest(agent, ownerScope))) {
+      throw directContinuationRecoveryDenied();
+    }
+    this.deferredAgents.set(agent.id, agent);
+    const recovered = await this.recoverRoutedDeferredTask(operationId, routed, publishTerminalTaskStatus);
+    if (!recovered) {
+      if (routed.state.continuationClaimed === true) {
+        throw new DirectContinuationRecoveryError(
+          "The direct continuation is already being resumed; do not redispatch the mutation.",
+          "in_progress"
+        );
+      }
+      throw directContinuationRecoveryDenied();
+    }
+    return {
+      ...recovered,
+      result: attachDirectContinuationRecovery(recovered.result, { operationId, recoveryKey }),
+      ...routed.state.clientContext !== void 0 && {
+        clientContext: structuredClone(routed.state.clientContext)
+      }
+    };
+  }
   async recoverRoutedDeferredTask(operationId, routed, publishTerminalTaskStatus) {
     const { token, state } = routed;
     if (state.settlementOperationId !== operationId || state.settlementOperationRouteRequired !== true || state.expiresAt <= Date.now()) {
@@ -2442,7 +2603,9 @@ class TaskExecutor {
       };
     }
     if (state.continuationClaimed) {
-      return void 0;
+      const lease = state.settlementResumeDispatchLease;
+      const reclaimableAdmission = state.directContinuationRecovery === true && lease?.phase === "admission" && Number.isFinite(lease.expiresAt) && lease.expiresAt <= Date.now();
+      if (!reclaimableAdmission) return void 0;
     }
     if (!state.pauseStatus || !state.pauseQuestion) {
       throw new DeferredSettlementOwnershipError(
@@ -2499,6 +2662,11 @@ class TaskExecutor {
       });
     }
     if (!state) throw new Error("The linked deferred callback checkpoint is unavailable.");
+    if (state.directContinuationRecovery === true) {
+      throw new DeferredSettlementOwnershipError(
+        "A direct continuation route cannot be checkpointed through committed settlement authorization."
+      );
+    }
     if (state.settlementOperationId !== operationId) {
       throw new Error("The deferred callback token is bound to a different committed operation.");
     }
@@ -2571,6 +2739,11 @@ class TaskExecutor {
     }
     const currentRoute = await this.loadDeferredSettlementOperationRoute(storage, operationId);
     if (!currentRoute) return void 0;
+    if (currentRoute.state.directContinuationRecovery === true) {
+      throw new DeferredSettlementOwnershipError(
+        "A direct continuation route cannot be checkpointed through committed settlement authorization."
+      );
+    }
     if (currentRoute.state.settlementOperationRouteRequired !== true) {
       throw new DeferredSettlementOwnershipError("The callback operation route is not a current-format checkpoint.");
     }
@@ -2610,9 +2783,21 @@ class TaskExecutor {
       throw new Error("Deferred task expired.");
     }
     const committedOperationId = state.settlementOperationId;
-    const requiresSettlement = committedOperationId !== void 0;
+    const operationRouteRequired = committedOperationId !== void 0 && state.settlementOperationRouteRequired === true;
+    const requiresSettlement = committedOperationId !== void 0 && state.directContinuationRecovery !== true;
+    const requiresRoutedAdmission = requiresSettlement || operationRouteRequired;
     const requiresRecoveredSettlement = requiresSettlement && !liveSettlementOwner;
-    if (requiresSettlement && state.settlementOperationRouteRequired === true) {
+    if (operationRouteRequired && state.directContinuationRecovery !== true && (state.directContinuationRecoveryKeyDigest !== void 0 || state.directContinuationOwnerBindingDigest !== void 0)) {
+      throw new DeferredSettlementOwnershipError(
+        "The direct continuation route lost its route-kind discriminator in durable storage."
+      );
+    }
+    if (state.directContinuationRecovery === true && (typeof state.directContinuationRecoveryKeyDigest !== "string" || typeof state.directContinuationOwnerBindingDigest !== "string")) {
+      throw new DeferredSettlementOwnershipError(
+        "The direct continuation route is missing its recovery ownership binding."
+      );
+    }
+    if (operationRouteRequired) {
       this.requireDeferredSettlementOperationRouting(this.config.deferredStorage);
     }
     if (requiresSettlement && state.settlementFinalizedResult !== void 0) {
@@ -2648,7 +2833,7 @@ class TaskExecutor {
         );
       }
     }
-    if (requiresSettlement && state.settlementOperationRouteRequired === true) {
+    if (operationRouteRequired) {
       const currentRoute = await this.loadDeferredSettlementOperationRoute(
         this.config.deferredStorage,
         committedOperationId
@@ -2659,6 +2844,12 @@ class TaskExecutor {
             "The committed continuation operation route does not match its stored generation."
           );
         }
+        if (state.directContinuationRecovery === true) {
+          throw new DirectContinuationRecoveryError(
+            "The direct continuation advanced to a newer generation; use owner-bound operation recovery.",
+            "superseded"
+          );
+        }
         if (state.settlementResumeAuthorizationRequired === true) {
           let replacementAuthorized = await this.config.authorizeDeferredSettlementResume?.(committedOperationId, currentRoute.token) === true;
           if (!replacementAuthorized) {
@@ -2789,7 +2980,7 @@ class TaskExecutor {
     }
     if (state.continuationClaimed) {
       const dispatchLease = state.settlementResumeDispatchLease;
-      const reclaimableAdmission = requiresSettlement && dispatchLease?.phase === "admission" && Number.isFinite(dispatchLease.expiresAt) && dispatchLease.expiresAt <= Date.now();
+      const reclaimableAdmission = requiresRoutedAdmission && dispatchLease?.phase === "admission" && Number.isFinite(dispatchLease.expiresAt) && dispatchLease.expiresAt <= Date.now();
       if (!reclaimableAdmission) {
         throw new DeferredSettlementOwnershipError("Deferred task is already being resumed.");
       }
@@ -2802,7 +2993,7 @@ class TaskExecutor {
     const claimTtlSeconds = this.deferredSafetyRetentionSeconds();
     const claimedVersion = randomUUID();
     const claimedAt = Date.now();
-    const dispatchOwnerId = requiresSettlement ? randomUUID() : void 0;
+    const dispatchOwnerId = requiresRoutedAdmission ? randomUUID() : void 0;
     const claimedMessages = durableDeferredSnapshot(state.messages);
     const resumedMessages = durableDeferredSnapshot(state.messages);
     const claimedState = {
@@ -2973,7 +3164,7 @@ class TaskExecutor {
         }
         const nextToken = resumed.deferred.token;
         assertDeferredContinuationToken(nextToken);
-        const replacementServerTaskId = requiresSettlement ? reconcileDeferredServerTaskId(trustedDeferredServerTaskId(state), [resumed.metadata.serverTaskId]) : resumed.metadata.serverTaskId;
+        const replacementServerTaskId = requiresSettlement ? reconcileDeferredServerTaskId(trustedDeferredServerTaskId(state), [resumed.metadata.serverTaskId]) : resumed.metadata.serverTaskId ?? state.settlementServerTaskId;
         const createdAt = Date.now();
         const ttlSeconds = this.config.deferredTaskTtlSeconds ?? DEFAULT_DEFERRED_TASK_TTL_SECONDS;
         const replacementState = {
@@ -3002,6 +3193,11 @@ class TaskExecutor {
           ...state.settlementOperationRouteRequired === true && {
             settlementOperationRouteRequired: true
           },
+          ...state.directContinuationRecovery === true && {
+            directContinuationRecovery: true,
+            directContinuationRecoveryKeyDigest: state.directContinuationRecoveryKeyDigest,
+            directContinuationOwnerBindingDigest: state.directContinuationOwnerBindingDigest
+          },
           ...state.settlementResumeAuthorizationRequired === true && {
             settlementResumeAuthorizationRequired: true
           },
@@ -3011,7 +3207,7 @@ class TaskExecutor {
           createdAt,
           expiresAt: createdAt + ttlSeconds * 1e3
         };
-        const stored = requiresSettlement && state.settlementOperationRouteRequired === true ? await this.config.deferredStorage.replaceForSettlementOperationIfVersion(
+        const stored = operationRouteRequired ? await this.config.deferredStorage.replaceForSettlementOperationIfVersion(
           committedOperationId,
           token,
           dispatchVersion,
@@ -4275,6 +4471,7 @@ export {
   DEFERRED_SETTLEMENT_ACK,
   DeferredSettlementOwnershipError,
   DeferredTaskError,
+  DirectContinuationRecoveryError,
   InputRequiredError,
   MaxClarificationError,
   TaskExecutor,

package/dist/lib/index.d.mts

@@ -26,12 +26,12 @@ export { InMemoryEstablishedProposalStore, createInMemoryEstablishedProposalStor
 export { ADCPMultiAgentClient, createADCPMultiAgentClient, type MultiAgentWebhookHandlerAdapter, } from './core/ADCPMultiAgentClient.mjs';
 export { ConfigurationManager } from './core/ConfigurationManager.mjs';
 export { CreativeAgentClient, createCreativeAgentClient, STANDARD_CREATIVE_AGENTS, type CreativeAgentListTaskOptions, type CreativeAgentClientConfig, type LegacyCreativeFormat, } from './core/CreativeAgentClient.mjs';
-export { TaskExecutor } from './core/TaskExecutor.mjs';
+export { TaskExecutor, DeferredSettlementOwnershipError, DirectContinuationRecoveryError, type DirectContinuationRecoveryFailure, } from './core/TaskExecutor.mjs';
 export { match, attachMatch } from './core/match.mjs';
 export type { MatchHandlers, PartialMatchHandlers } from './core/match.mjs';
 export { ProtocolResponseParser, responseParser, ADCP_STATUS, type ADCPStatus } from './core/ProtocolResponseParser.mjs';
 export { ResponseValidator, responseValidator, type ValidationResult, type ValidationOptions, } from './core/ResponseValidator.mjs';
-export type { Message, InputRequest, InputHandler, InputHandlerResponse, ConversationContext, TaskOptions, WebhookToolPredicate, WebhookUrlTemplate, TaskResult, TaskResultCompleted, TaskResultIntermediate, TaskResultFailure, TaskResultMetadata, TaskState, TaskStatus, ConversationConfig, AdcpErrorInfo, AdcpValidationIssue, } from './core/ConversationTypes.mjs';
+export type { Message, InputRequest, InputHandler, InputHandlerResponse, ConversationContext, TaskOptions, WebhookToolPredicate, WebhookUrlTemplate, TaskResult, TaskResultCompleted, TaskResultIntermediate, TaskResultFailure, TaskResultMetadata, DeferredContinuation, DirectPauseRecoveryRequest, TaskState, TaskStatus, ConversationConfig, AdcpErrorInfo, AdcpValidationIssue, } from './core/ConversationTypes.mjs';
 export type { GovernanceConfig, CampaignGovernanceConfig, GovernanceCheckResult, GovernanceOutcome, GovernanceFinding, GovernanceIntentDetails, GovernanceCondition, GovernanceEscalation, NormalizedGovernanceApproved, NormalizedGovernanceConditions, NormalizedGovernanceDenied, NormalizedGovernanceVerdict, } from './core/GovernanceTypes.mjs';
 export { GovernanceMiddleware } from './core/GovernanceMiddleware.mjs';
 export { isGovernanceApproved, isGovernanceConditions, isGovernanceDenied, normalizeGovernanceVerdict, } from './core/GovernanceTypes.mjs';
@@ -263,3 +263,6 @@ export * from './client/account-changes.mjs';
 export * from './client/account-change-subscription.mjs';
 export * from './notifications/account-change-recorded.mjs';
 export type { AccountChangeFeedCapabilities } from './utils/capabilities.mjs';
+export * from './media-buy/actions.mjs';
+export { mediaBuyActionResolver } from './server/media-buy-action-resolver.mjs';
+export type { SellerActionDecision, SellerActionResolutionOptions, SellerActionResolution, } from './server/media-buy-action-resolver.mjs';

package/dist/lib/index.d.ts

@@ -26,12 +26,12 @@ export { InMemoryEstablishedProposalStore, createInMemoryEstablishedProposalStor
 export { ADCPMultiAgentClient, createADCPMultiAgentClient, type MultiAgentWebhookHandlerAdapter, } from './core/ADCPMultiAgentClient';
 export { ConfigurationManager } from './core/ConfigurationManager';
 export { CreativeAgentClient, createCreativeAgentClient, STANDARD_CREATIVE_AGENTS, type CreativeAgentListTaskOptions, type CreativeAgentClientConfig, type LegacyCreativeFormat, } from './core/CreativeAgentClient';
-export { TaskExecutor } from './core/TaskExecutor';
+export { TaskExecutor, DeferredSettlementOwnershipError, DirectContinuationRecoveryError, type DirectContinuationRecoveryFailure, } from './core/TaskExecutor';
 export { match, attachMatch } from './core/match';
 export type { MatchHandlers, PartialMatchHandlers } from './core/match';
 export { ProtocolResponseParser, responseParser, ADCP_STATUS, type ADCPStatus } from './core/ProtocolResponseParser';
 export { ResponseValidator, responseValidator, type ValidationResult, type ValidationOptions, } from './core/ResponseValidator';
-export type { Message, InputRequest, InputHandler, InputHandlerResponse, ConversationContext, TaskOptions, WebhookToolPredicate, WebhookUrlTemplate, TaskResult, TaskResultCompleted, TaskResultIntermediate, TaskResultFailure, TaskResultMetadata, TaskState, TaskStatus, ConversationConfig, AdcpErrorInfo, AdcpValidationIssue, } from './core/ConversationTypes';
+export type { Message, InputRequest, InputHandler, InputHandlerResponse, ConversationContext, TaskOptions, WebhookToolPredicate, WebhookUrlTemplate, TaskResult, TaskResultCompleted, TaskResultIntermediate, TaskResultFailure, TaskResultMetadata, DeferredContinuation, DirectPauseRecoveryRequest, TaskState, TaskStatus, ConversationConfig, AdcpErrorInfo, AdcpValidationIssue, } from './core/ConversationTypes';
 export type { GovernanceConfig, CampaignGovernanceConfig, GovernanceCheckResult, GovernanceOutcome, GovernanceFinding, GovernanceIntentDetails, GovernanceCondition, GovernanceEscalation, NormalizedGovernanceApproved, NormalizedGovernanceConditions, NormalizedGovernanceDenied, NormalizedGovernanceVerdict, } from './core/GovernanceTypes';
 export { GovernanceMiddleware } from './core/GovernanceMiddleware';
 export { isGovernanceApproved, isGovernanceConditions, isGovernanceDenied, normalizeGovernanceVerdict, } from './core/GovernanceTypes';
@@ -263,3 +263,6 @@ export * from './client/account-changes';
 export * from './client/account-change-subscription';
 export * from './notifications/account-change-recorded';
 export type { AccountChangeFeedCapabilities } from './utils/capabilities';
+export * from './media-buy/actions';
+export { mediaBuyActionResolver } from './server/media-buy-action-resolver';
+export type { SellerActionDecision, SellerActionResolutionOptions, SellerActionResolution, } from './server/media-buy-action-resolver';

package/dist/lib/index.js

@@ -68,7 +68,9 @@ __export(index_exports, {
   DEFAULT_REPORTING_CAPABILITIES: () => import_server.DEFAULT_REPORTING_CAPABILITIES,
   DEFAULT_SSRF_POLICY: () => import_substitution.DEFAULT_SSRF_POLICY,
   DISCOVERY_ARM_SCENARIOS: () => import_server.DISCOVERY_ARM_SCENARIOS,
+  DeferredSettlementOwnershipError: () => import_TaskExecutor.DeferredSettlementOwnershipError,
   DeferredTaskError: () => import_errors.DeferredTaskError,
+  DirectContinuationRecoveryError: () => import_TaskExecutor.DirectContinuationRecoveryError,
   ESTABLISHED_PROPOSAL_COMPLETION_TOMBSTONE_RETENTION_MS: () => import_established_proposal_store.ESTABLISHED_PROPOSAL_COMPLETION_TOMBSTONE_RETENTION_MS,
   EVENT_TRACKING_TOOLS: () => import_capabilities.EVENT_TRACKING_TOOLS,
   FeatureUnsupportedError: () => import_errors.FeatureUnsupportedError,
@@ -539,6 +541,7 @@ __export(index_exports, {
   markdownGroupAsset: () => import_format_asset_slot_builders.markdownGroupAsset,
   match: () => import_match.match,
   matchBindings: () => import_substitution.matchBindings,
+  mediaBuyActionResolver: () => import_media_buy_action_resolver.mediaBuyActionResolver,
   mediaBuyDeliveryNotification: () => import_media_buy_delivery_notification_builders.mediaBuyDeliveryNotification,
   memoryBackend: () => import_server.memoryBackend,
   multiBuildCreativeReturn: () => import_build_creative_return_builders.multiBuildCreativeReturn,
@@ -810,6 +813,8 @@ __reExport(index_exports, require('./client/account-change-cursor.js'), module.e
 __reExport(index_exports, require('./client/account-changes.js'), module.exports);
 __reExport(index_exports, require('./client/account-change-subscription.js'), module.exports);
 __reExport(index_exports, require('./notifications/account-change-recorded.js'), module.exports);
+__reExport(index_exports, require('./media-buy/actions.js'), module.exports);
+var import_media_buy_action_resolver = require('./server/media-buy-action-resolver.js');
 const wireVersion = {
   isSupported: import_protocols2.bundleSupportsAdcpVersionField,
   normalize: import_schema_loader2.toReleasePrecisionWire,
@@ -873,7 +878,9 @@ function createAdCPClientFromEnv() {
   DEFAULT_REPORTING_CAPABILITIES,
   DEFAULT_SSRF_POLICY,
   DISCOVERY_ARM_SCENARIOS,
+  DeferredSettlementOwnershipError,
   DeferredTaskError,
+  DirectContinuationRecoveryError,
   ESTABLISHED_PROPOSAL_COMPLETION_TOMBSTONE_RETENTION_MS,
   EVENT_TRACKING_TOOLS,
   FeatureUnsupportedError,
@@ -1344,6 +1351,7 @@ function createAdCPClientFromEnv() {
   markdownGroupAsset,
   match,
   matchBindings,
+  mediaBuyActionResolver,
   mediaBuyDeliveryNotification,
   memoryBackend,
   multiBuildCreativeReturn,
@@ -1512,5 +1520,6 @@ function createAdCPClientFromEnv() {
   ...require('./client/account-change-cursor.js'),
   ...require('./client/account-changes.js'),
   ...require('./client/account-change-subscription.js'),
-  ...require('./notifications/account-change-recorded.js')
+  ...require('./notifications/account-change-recorded.js'),
+  ...require('./media-buy/actions.js')
 });

package/dist/lib/index.mjs

@@ -117,7 +117,11 @@ import {
   createCreativeAgentClient,
   STANDARD_CREATIVE_AGENTS
 } from "./core/CreativeAgentClient.mjs";
-import { TaskExecutor } from "./core/TaskExecutor.mjs";
+import {
+  TaskExecutor,
+  DeferredSettlementOwnershipError,
+  DirectContinuationRecoveryError
+} from "./core/TaskExecutor.mjs";
 import { match, attachMatch } from "./core/match.mjs";
 import { ProtocolResponseParser, responseParser, ADCP_STATUS } from "./core/ProtocolResponseParser.mjs";
 import {
@@ -779,6 +783,8 @@ export * from "./client/account-change-cursor.mjs";
 export * from "./client/account-changes.mjs";
 export * from "./client/account-change-subscription.mjs";
 export * from "./notifications/account-change-recorded.mjs";
+export * from "./media-buy/actions.mjs";
+import { mediaBuyActionResolver } from "./server/media-buy-action-resolver.mjs";
 export {
   A2AInvocationError,
   A2A_CARD_PATHS,
@@ -829,7 +835,9 @@ export {
   DEFAULT_REPORTING_CAPABILITIES,
   DEFAULT_SSRF_POLICY,
   DISCOVERY_ARM_SCENARIOS,
+  DeferredSettlementOwnershipError,
   DeferredTaskError,
+  DirectContinuationRecoveryError,
   ESTABLISHED_PROPOSAL_COMPLETION_TOMBSTONE_RETENTION_MS,
   EVENT_TRACKING_TOOLS,
   FeatureUnsupportedError,
@@ -1300,6 +1308,7 @@ export {
   markdownGroupAsset,
   match,
   matchBindings,
+  mediaBuyActionResolver,
   mediaBuyDeliveryNotification,
   memoryBackend,
   multiBuildCreativeReturn,

package/dist/lib/media-buy/action-assessment.d.mts

@@ -0,0 +1,77 @@
+import type { ActionNotAllowedReason, UpdateMediaBuyRequestLike } from './types.mjs';
+import type { ActionBuy, ActionProduct, ActionProposal, ConstraintAssessment, LiveMediaBuyAction, MediaBuyAction, MediaBuyStatus, MediaBuyTask, ProductActionAssessment, ProposalActionAssessment, ProposalChangeTerm } from './action-types.mjs';
+import { type ConstraintEvaluationOptions } from './action-constraints.mjs';
+export interface ActionAssessmentOptions extends ConstraintEvaluationOptions {
+    /** Seller-served wire version. 3.1 term references are always opaque. Defaults to the current 3.2 shape. */
+    adcpVersion?: string;
+    /** Explicit 3.2 compatibility projection declaring terms_ref an alias for change_term_id. */
+    termsRefIsAlias?: boolean;
+    /** Current accepted snapshot when it is stored separately from the buy. An embedded snapshot takes precedence. */
+    proposal?: ActionProposal;
+    /** Optional route being attempted. update_media_buy can subsume compact tasks as a compatibility facade. */
+    task?: MediaBuyTask;
+    request?: UpdateMediaBuyRequestLike;
+}
+export type ActionAvailability = {
+    status: 'available_now';
+    action: MediaBuyAction;
+    mode: LiveMediaBuyAction['mode'];
+    nonDefaultRoute?: MediaBuyTask;
+    /** Metadata changes have live seller authority and no commercial promise. */
+    authority: 'accepted_term' | 'live_metadata';
+    term?: ProposalChangeTerm;
+    entry: LiveMediaBuyAction;
+    revision?: number;
+    constraints?: ConstraintAssessment;
+} | {
+    status: 'currently_unavailable';
+    action: MediaBuyAction;
+    reason: ActionNotAllowedReason;
+    message: string;
+    certainty: 'blocked' | 'unknown';
+    allowedStatuses?: MediaBuyStatus[];
+    nonDefaultRoute?: MediaBuyTask;
+    constraints?: ConstraintAssessment;
+    code?: 'REQUOTE_REQUIRED' | 'CONFLICT';
+    compat?: {
+        reason: 'no_change_terms';
+        message: string;
+    };
+};
+export interface MediaBuyActionAssessment {
+    action: MediaBuyAction;
+    possibility: ProductActionAssessment;
+    promise: ProposalActionAssessment;
+    availability: ActionAvailability;
+}
+/** Product templates are possibility, including their advisory bounds, never acceptance. */
+export declare function assessProductAction(product: ActionProduct | undefined, action: MediaBuyAction): ProductActionAssessment;
+/** Reports what the proposal promises; it does not verify a digest or accept the proposal. */
+export declare function assessProposalAction(proposal: ActionProposal | undefined, action: MediaBuyAction): ProposalActionAssessment;
+/**
+ * Join the current accepted snapshot and action projection. Pure, synchronous,
+ * browser-safe, and read-only. This is preflight evidence, not authorization or
+ * an atomic revision check. Submit with the existing client lifecycle safeguards.
+ */
+export declare function assessActionAvailability(buy: ActionBuy | undefined, action: MediaBuyAction, options?: ActionAssessmentOptions): ActionAvailability;
+/** Render possible / promised / available-now from one call. Product data never creates a promise. */
+export declare function assessMediaBuyAction(input: {
+    action: MediaBuyAction;
+    product?: ActionProduct;
+    proposal?: ActionProposal;
+    buy?: ActionBuy;
+} & ActionAssessmentOptions): MediaBuyActionAssessment;
+/** ACTION_NOT_ALLOWED echoes replace the action set, including an explicit empty set. They never update revision or accepted terms. */
+export declare function refreshMediaBuyActions<T extends ActionBuy>(buy: T, details: unknown): T;
+export type MediaBuyActionsPreflight = {
+    ok: true;
+    assessments: Extract<ActionAvailability, {
+        status: 'available_now';
+    }>[];
+} | {
+    ok: false;
+    assessments: ActionAvailability[];
+    message?: string;
+};
+/** Assess every decomposed action atomically; never send a partial multi-action request. */
+export declare function preflightMediaBuyActions(buy: ActionBuy, request: UpdateMediaBuyRequestLike, options?: Omit<ActionAssessmentOptions, 'request'>): MediaBuyActionsPreflight;