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

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

@@ -5,7 +5,7 @@ import { type MutatingRequestInput } from '../utils/idempotency';
 import type { MCPWebhookPayload, TaskStatus } from '../types/core.generated';
 type A2ATask = Record<string, any>;
 type TaskStatusUpdateEvent = Record<string, any>;
-import type { InputHandler, Message, TaskOptions, TaskResult, ConversationConfig, TaskInfo, TaskState, WebhookUrlTemplate } from './ConversationTypes';
+import type { InputHandler, Message, TaskOptions, TaskResult, ConversationConfig, TaskInfo, TaskState, WebhookUrlTemplate, DirectPauseRecoveryRequest } from './ConversationTypes';
 import type { AdcpTaskName, TaskRequestFor, TaskResponseTypeMap } from './AgentClient';
 import type { DeferredTaskStorage } from '../storage/interfaces';
 import type { Activity, AsyncHandlerConfig } from './AsyncHandler';
@@ -523,6 +523,8 @@ export declare class SingleAgentClient {
      * version. Wire-shape adapters key off this method in subsequent stages.
      */
     getAdcpVersion(): string;
+    /** Recover the current generation of an opt-in direct mutation pause. */
+    recoverDirectPauseContinuation<T>(request: DirectPauseRecoveryRequest): Promise<TaskResult<T>>;
     private recoverDurableSettlement;
     private recoverPersistedDeferredTerminal;
     private taskResultFromRecoveredSettlement;

package/dist/lib/core/SingleAgentClient.js

@@ -503,6 +503,9 @@ 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 }
     }
   };
 }
@@ -1309,6 +1312,11 @@ class SingleAgentClient {
   recoverDeferredTaskForOperation(operationId, recoveryKey, publishTerminalTaskStatus = true) {
     return this.executor.recoverDeferredTaskForOperation(operationId, recoveryKey, publishTerminalTaskStatus);
   }
+  /** Recover the current generation of an opt-in direct mutation pause. */
+  async recoverDirectPauseContinuation(request) {
+    const recovered = await this.executor.recoverDirectPauseContinuation(request);
+    return isDeferredClientFinalizationContext(recovered.clientContext) ? this.finalizeTaskResult(recovered.result, recovered.clientContext) : recovered.result;
+  }
   /** Bridge a store-recovered callback into the deferred terminal checkpoint. @internal */
   checkpointExternalDeferredSettlement(token, operationId, terminalResult) {
     return this.executor.checkpointExternalDeferredSettlement(token, operationId, terminalResult);
@@ -5033,7 +5041,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       if (error instanceof import_TaskExecutor.BeforeProtocolDispatchHookError || error instanceof import_TaskExecutor.AfterProtocolDispatchHookError) {
         throw error.original;
       }
-      if (error instanceof import_errors.AuthenticationRequiredError || error instanceof import_errors.TaskTimeoutError || error instanceof import_errors.VersionUnsupportedError || error instanceof import_errors.FeatureUnsupportedError || (0, import_abort.isAbortOrTimeoutError)(error)) {
+      if (error instanceof import_errors.AuthenticationRequiredError || error instanceof import_errors.TaskTimeoutError || error instanceof import_errors.VersionUnsupportedError || error instanceof import_errors.FeatureUnsupportedError || error instanceof import_errors.ConfigurationError && options?.durableContinuationRecovery !== void 0 || (0, import_abort.isAbortOrTimeoutError)(error)) {
         throw error;
       }
       const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/lib/core/SingleAgentClient.mjs

@@ -557,6 +557,9 @@ 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 }
     }
   };
 }
@@ -1363,6 +1366,11 @@ class SingleAgentClient {
   recoverDeferredTaskForOperation(operationId, recoveryKey, publishTerminalTaskStatus = true) {
     return this.executor.recoverDeferredTaskForOperation(operationId, recoveryKey, publishTerminalTaskStatus);
   }
+  /** Recover the current generation of an opt-in direct mutation pause. */
+  async recoverDirectPauseContinuation(request) {
+    const recovered = await this.executor.recoverDirectPauseContinuation(request);
+    return isDeferredClientFinalizationContext(recovered.clientContext) ? this.finalizeTaskResult(recovered.result, recovered.clientContext) : recovered.result;
+  }
   /** Bridge a store-recovered callback into the deferred terminal checkpoint. @internal */
   checkpointExternalDeferredSettlement(token, operationId, terminalResult) {
     return this.executor.checkpointExternalDeferredSettlement(token, operationId, terminalResult);
@@ -5087,7 +5095,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       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)) {
+      if (error instanceof AuthenticationRequiredError || error instanceof TaskTimeoutError || error instanceof VersionUnsupportedError || error instanceof FeatureUnsupportedError || error instanceof ConfigurationError && options?.durableContinuationRecovery !== void 0 || isAbortOrTimeoutError(error)) {
         throw error;
       }
       const errorMessage = error instanceof Error ? error.message : String(error);

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

@@ -2,7 +2,7 @@ import type { AgentConfig } from '../types/index.mjs';
 import type { DeferredTaskStorage } from '../storage/interfaces.mjs';
 import { type ValidationHookConfig } from '../validation/client-hooks.mjs';
 import type { AdcpCapabilities } from '../utils/capabilities.mjs';
-import type { Message, InputHandler, TaskOptions, TaskResult, TaskState, TaskStatus, TaskInfo, WebhookUrlTemplate } from './ConversationTypes.mjs';
+import type { Message, InputHandler, TaskOptions, TaskResult, TaskState, TaskStatus, TaskInfo, DirectPauseRecoveryRequest, WebhookUrlTemplate } from './ConversationTypes.mjs';
 import type { Activity } from './AsyncHandler.mjs';
 import { GovernanceMiddleware } from './GovernanceMiddleware.mjs';
 import type { GovernanceConfig } from './GovernanceTypes.mjs';
@@ -25,6 +25,12 @@ export declare const DEFERRED_SETTLEMENT_ACK: unique symbol;
 export declare class DeferredSettlementOwnershipError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
+export type DirectContinuationRecoveryFailure = 'not_authorized' | 'in_progress' | 'superseded';
+/** Typed failure from the public direct-continuation recovery boundary. */
+export declare class DirectContinuationRecoveryError extends DeferredSettlementOwnershipError {
+    readonly reason: DirectContinuationRecoveryFailure;
+    constructor(message: string, reason: DirectContinuationRecoveryFailure);
+}
 /** Carry only the SDK's private settlement controls across an internal result projection. */
 export declare function transferDeferredSettlementAcknowledgement<T extends object>(source: object, target: T): T;
 /** Identify the internal submitted continuation that owns a durable pending checkpoint. */
@@ -339,6 +345,12 @@ export declare class TaskExecutor {
     private requireDeferredSettlementOperationRouting;
     private loadDeferredSettlementOperationRoute;
     private replaceDeferredState;
+    /** Recover an opt-in direct continuation through its secret operation capability. */
+    recoverDirectPauseContinuation<T>(request: DirectPauseRecoveryRequest, publishTerminalTaskStatus?: boolean): Promise<{
+        token: string;
+        result: TaskResult<T>;
+        clientContext?: unknown;
+    }>;
     private recoverRoutedDeferredTask;
     /** A live owner closure may carry its committed settlement wrapper in process. */
     private resumeDeferredTaskFromLiveClosure;

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

@@ -2,7 +2,7 @@ import type { AgentConfig } from '../types';
 import type { DeferredTaskStorage } from '../storage/interfaces';
 import { type ValidationHookConfig } from '../validation/client-hooks';
 import type { AdcpCapabilities } from '../utils/capabilities';
-import type { Message, InputHandler, TaskOptions, TaskResult, TaskState, TaskStatus, TaskInfo, WebhookUrlTemplate } from './ConversationTypes';
+import type { Message, InputHandler, TaskOptions, TaskResult, TaskState, TaskStatus, TaskInfo, DirectPauseRecoveryRequest, WebhookUrlTemplate } from './ConversationTypes';
 import type { Activity } from './AsyncHandler';
 import { GovernanceMiddleware } from './GovernanceMiddleware';
 import type { GovernanceConfig } from './GovernanceTypes';
@@ -25,6 +25,12 @@ export declare const DEFERRED_SETTLEMENT_ACK: unique symbol;
 export declare class DeferredSettlementOwnershipError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
+export type DirectContinuationRecoveryFailure = 'not_authorized' | 'in_progress' | 'superseded';
+/** Typed failure from the public direct-continuation recovery boundary. */
+export declare class DirectContinuationRecoveryError extends DeferredSettlementOwnershipError {
+    readonly reason: DirectContinuationRecoveryFailure;
+    constructor(message: string, reason: DirectContinuationRecoveryFailure);
+}
 /** Carry only the SDK's private settlement controls across an internal result projection. */
 export declare function transferDeferredSettlementAcknowledgement<T extends object>(source: object, target: T): T;
 /** Identify the internal submitted continuation that owns a durable pending checkpoint. */
@@ -339,6 +345,12 @@ export declare class TaskExecutor {
     private requireDeferredSettlementOperationRouting;
     private loadDeferredSettlementOperationRoute;
     private replaceDeferredState;
+    /** Recover an opt-in direct continuation through its secret operation capability. */
+    recoverDirectPauseContinuation<T>(request: DirectPauseRecoveryRequest, publishTerminalTaskStatus?: boolean): Promise<{
+        token: string;
+        result: TaskResult<T>;
+        clientContext?: unknown;
+    }>;
     private recoverRoutedDeferredTask;
     /** A live owner closure may carry its committed settlement wrapper in process. */
     private resumeDeferredTaskFromLiveClosure;

package/dist/lib/core/TaskExecutor.js

@@ -23,6 +23,7 @@ __export(TaskExecutor_exports, {
   DEFERRED_SETTLEMENT_ACK: () => DEFERRED_SETTLEMENT_ACK,
   DeferredSettlementOwnershipError: () => DeferredSettlementOwnershipError,
   DeferredTaskError: () => DeferredTaskError,
+  DirectContinuationRecoveryError: () => DirectContinuationRecoveryError,
   InputRequiredError: () => InputRequiredError,
   MaxClarificationError: () => MaxClarificationError,
   TaskExecutor: () => TaskExecutor,
@@ -102,6 +103,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);
@@ -375,9 +384,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 (0, import_crypto.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 && (0, import_crypto.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 import_errors.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(
+    (0, import_jcs.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 };
 }
@@ -708,6 +771,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 import_errors.ConfigurationError("durableContinuationRecovery is supported only for resumable A2A mutations.");
+      }
+      if (!(0, import_idempotency.requestUsesIdempotency)(taskName, params)) {
+        throw new import_errors.ConfigurationError("durableContinuationRecovery is supported only for mutating AdCP requests.");
+      }
+      if (!this.config.deferredStorage) {
+        throw new import_errors.ConfigurationError("durableContinuationRecovery requires deferredStorage.");
+      }
+      this.requireDeferredSettlementOperationRouting(this.config.deferredStorage, true);
+    }
     const taskId = (0, import_task_deadline.getTaskOperationId)(options) ?? (0, import_crypto.randomUUID)();
     const startTime = Date.now();
     const workingTimeout = this.config.workingTimeout || 12e4;
@@ -1797,7 +1873,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({
@@ -1834,6 +1912,7 @@ class TaskExecutor {
       const token = (0, import_crypto.randomUUID)();
       const deferredStorage = this.config.deferredStorage;
       const usesDurableStorage = deferredStorage !== void 0 && persistPausedContinuation;
+      const directRecoveryKey = directContinuationRecovery && usesDurableStorage ? (0, import_crypto.randomBytes)(32).toString("base64url") : void 0;
       if (usesDurableStorage) {
         const createdAt = Date.now();
         const ttlSeconds = this.config.deferredTaskTtlSeconds ?? DEFAULT_DEFERRED_TASK_TTL_SECONDS;
@@ -1857,10 +1936,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
           },
@@ -1868,8 +1955,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.");
         }
@@ -1910,6 +1999,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
@@ -1958,6 +2053,7 @@ class TaskExecutor {
       const token = handlerResponse.token;
       const deferredStorage = this.config.deferredStorage;
       const usesDurableStorage = deferredStorage !== void 0 && persistPausedContinuation;
+      const directRecoveryKey = directContinuationRecovery && usesDurableStorage ? (0, import_crypto.randomBytes)(32).toString("base64url") : void 0;
       if (usesDurableStorage) {
         assertDeferredContinuationToken(token);
         const createdAt = Date.now();
@@ -1982,10 +2078,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
           },
@@ -1993,8 +2097,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.");
         }
@@ -2036,6 +2142,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
@@ -2400,10 +2512,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 import_errors.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."
       );
     }
   }
@@ -2421,7 +2533,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,
@@ -2454,8 +2566,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 import_errors.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()) {
@@ -2468,7 +2630,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(
@@ -2525,6 +2689,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.");
     }
@@ -2597,6 +2766,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.");
     }
@@ -2636,9 +2810,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) {
@@ -2674,7 +2860,7 @@ class TaskExecutor {
         );
       }
     }
-    if (requiresSettlement && state.settlementOperationRouteRequired === true) {
+    if (operationRouteRequired) {
       const currentRoute = await this.loadDeferredSettlementOperationRoute(
         this.config.deferredStorage,
         committedOperationId
@@ -2685,6 +2871,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) {
@@ -2815,7 +3007,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.");
       }
@@ -2828,7 +3020,7 @@ class TaskExecutor {
     const claimTtlSeconds = this.deferredSafetyRetentionSeconds();
     const claimedVersion = (0, import_crypto.randomUUID)();
     const claimedAt = Date.now();
-    const dispatchOwnerId = requiresSettlement ? (0, import_crypto.randomUUID)() : void 0;
+    const dispatchOwnerId = requiresRoutedAdmission ? (0, import_crypto.randomUUID)() : void 0;
     const claimedMessages = durableDeferredSnapshot(state.messages);
     const resumedMessages = durableDeferredSnapshot(state.messages);
     const claimedState = {
@@ -2999,7 +3191,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 = {
@@ -3028,6 +3220,11 @@ class TaskExecutor {
           ...state.settlementOperationRouteRequired === true && {
             settlementOperationRouteRequired: true
           },
+          ...state.directContinuationRecovery === true && {
+            directContinuationRecovery: true,
+            directContinuationRecoveryKeyDigest: state.directContinuationRecoveryKeyDigest,
+            directContinuationOwnerBindingDigest: state.directContinuationOwnerBindingDigest
+          },
           ...state.settlementResumeAuthorizationRequired === true && {
             settlementResumeAuthorizationRequired: true
           },
@@ -3037,7 +3234,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,
@@ -4302,6 +4499,7 @@ class TaskExecutor {
   DEFERRED_SETTLEMENT_ACK,
   DeferredSettlementOwnershipError,
   DeferredTaskError,
+  DirectContinuationRecoveryError,
   InputRequiredError,
   MaxClarificationError,
   TaskExecutor,