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

package/dist/lib/core/TaskExecutor.mjs

@@ -1,4 +1,4 @@
-import { randomUUID } from "crypto";
+import { createHash, randomUUID } from "crypto";
 import {
   ProtocolClient,
   normalizeTransportOptions,
@@ -65,6 +65,14 @@ class BeforeProtocolDispatchHookError extends Error {
   }
   original;
 }
+class AfterProtocolDispatchHookError extends Error {
+  constructor(original) {
+    super("An SDK post-dispatch settlement hook failed.", { cause: original });
+    this.original = original;
+    this.name = "AfterProtocolDispatchHookError";
+  }
+  original;
+}
 const GOVERNED_CREDENTIAL_SCAN_MAX_NODES = 1e4;
 const GOVERNED_CREDENTIAL_SCAN_MAX_DEPTH = 64;
 const GOVERNED_CALLBACK_FIELDS = /* @__PURE__ */ new Set(["push_notification_config", "reporting_webhook", "artifact_webhook"]);
@@ -230,6 +238,8 @@ function resolveIdempotencyKey(taskName, params, serverVersion) {
   return void 0;
 }
 const COMPACTED_TASK_STATE_LIMIT = 1e4;
+const DEFAULT_EXTERNAL_TASK_SETTLEMENT_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
+const MAX_TIMER_DELAY_MS = 2147483647;
 const TERMINAL_TASK_STATUSES = /* @__PURE__ */ new Set([
   "completed",
   "failed",
@@ -238,9 +248,14 @@ const TERMINAL_TASK_STATUSES = /* @__PURE__ */ new Set([
   "governance-denied",
   "aborted"
 ]);
+const MAX_PENDING_EXTERNAL_TASK_OBSERVATIONS = 8;
+const MAX_RETAINED_EXTERNAL_TASK_ERROR_CHARS = 1024;
 class TaskExecutor {
   constructor(config = {}) {
     this.config = config;
+    if (config.externalTaskSettlementRetentionMs !== void 0 && (!Number.isSafeInteger(config.externalTaskSettlementRetentionMs) || config.externalTaskSettlementRetentionMs < 1)) {
+      throw new ConfigurationError("externalTaskSettlementRetentionMs must be a positive safe integer.");
+    }
     this.responseParser = new ProtocolResponseParser();
     if (config.enableConversationStorage) {
       this.conversationStorage = /* @__PURE__ */ new Map();
@@ -265,6 +280,14 @@ class TaskExecutor {
     }
   }
   config;
+  deferredTerminalPublicationTaskIds = /* @__PURE__ */ new Set();
+  settlementCapacityReservations = /* @__PURE__ */ new Set();
+  closedExternalTaskSettlementTaskIds = /* @__PURE__ */ new Set();
+  externalTaskSettlementHandlers = /* @__PURE__ */ new Map();
+  externalTaskSettlementInFlight = /* @__PURE__ */ new Map();
+  settledExternalTaskObservationKeys = /* @__PURE__ */ new Map();
+  externalTaskSettlementExpiry = /* @__PURE__ */ new Map();
+  pendingExternalTaskObservations = /* @__PURE__ */ new Map();
   responseParser;
   activeTasks = /* @__PURE__ */ new Map();
   compactedTaskIds = /* @__PURE__ */ new Map();
@@ -290,9 +313,43 @@ class TaskExecutor {
    *
    * @internal
    */
-  observeExternalTaskStatus(taskId, status, result) {
-    if (!["completed", "failed", "rejected", "canceled"].includes(status)) return;
+  async observeExternalTaskStatus(taskId, status, result, identity = {}) {
+    if (!["completed", "failed", "rejected", "canceled", "governance-denied", "aborted"].includes(status)) {
+      return { settled: false, result };
+    }
+    const observation = { status, result, ...identity };
+    const observationKey = this.externalTaskObservationKey(observation);
+    if (this.closedExternalTaskSettlementTaskIds.has(taskId)) {
+      const accepted = this.settledExternalTaskObservationKeys.get(taskId);
+      if (accepted?.key === observationKey) {
+        return {
+          settled: true,
+          duplicate: true,
+          status: accepted.status,
+          ...accepted.error !== void 0 && { error: accepted.error }
+        };
+      }
+      throw new Error("This task already completed durable settlement; the pushed result was not accepted.");
+    }
+    if (this.deferredTerminalPublicationTaskIds.has(taskId)) {
+      const handler = this.externalTaskSettlementHandlers.get(taskId);
+      if (handler) return this.settleExternalTaskStatus(taskId, handler, observation);
+      return new Promise((resolve, reject) => {
+        const pending = this.pendingExternalTaskObservations.get(taskId) ?? [];
+        if (pending.length >= MAX_PENDING_EXTERNAL_TASK_OBSERVATIONS) {
+          reject(new Error("Too many terminal push notifications are awaiting durable task settlement."));
+          return;
+        }
+        pending.push({ observation, resolve, reject });
+        this.pendingExternalTaskObservations.set(taskId, pending);
+      });
+    }
     this.updateTaskStatus(taskId, status, result);
+    return { settled: false, result };
+  }
+  /** Whether this process can safely settle or reject a durable callback for the operation. */
+  hasExternalTaskSettlementRoute(taskId) {
+    return this.deferredTerminalPublicationTaskIds.has(taskId) || this.closedExternalTaskSettlementTaskIds.has(taskId) || this.externalTaskSettlementHandlers.has(taskId);
   }
   /**
    * Run the configured pre-send schema check against the user-facing request
@@ -389,6 +446,7 @@ class TaskExecutor {
   }
   async executeTaskWithinDeadline(agent, taskName, params, inputHandler, options = {}, serverVersion, targetCapabilities, beforeProtocolDispatch) {
     if (serverVersion) this.lastKnownServerVersion = serverVersion;
+    params = structuredClone(params);
     const taskId = getTaskOperationId(options) ?? randomUUID();
     const startTime = Date.now();
     const workingTimeout = this.config.workingTimeout || 12e4;
@@ -411,9 +469,14 @@ class TaskExecutor {
       idempotencyKey
     };
     this.activeTasks.set(taskId, taskState);
+    let dispatchBoundaryOwnsTerminalState = false;
     const taskAbortListener = options.signal ? () => {
       const currentStatus = this.activeTasks.get(taskId)?.status;
       if (currentStatus && !TERMINAL_TASK_STATUSES.has(currentStatus)) {
+        if (dispatchBoundaryOwnsTerminalState) {
+          this.compactAbandonedObserverTaskState(taskId);
+          return;
+        }
         const reason = options.signal?.reason;
         this.updateTaskStatus(
           taskId,
@@ -440,6 +503,9 @@ class TaskExecutor {
     let governanceResult;
     let effectiveParams = params;
     let governanceAdjusted = false;
+    let dispatchCommitted = false;
+    let dispatchSettlement;
+    let dispatchSettlementStarted = false;
     try {
       await this.config.onActivity?.({
         type: "protocol_request",
@@ -498,14 +564,15 @@ class TaskExecutor {
           effectiveParams = adjustedParams;
         }
       }
+      const dispatchParams = structuredClone(effectiveParams);
       const initialMessage = {
         id: randomUUID(),
         role: "user",
-        content: { tool: taskName, params: effectiveParams },
+        content: { tool: taskName, params: dispatchParams },
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         metadata: { toolName: taskName, type: "request" }
       };
-      const preparedCall = prepareProtocolToolCall(agent, effectiveParams, {
+      const preparedCall = prepareProtocolToolCall(agent, dispatchParams, {
         toolName: taskName,
         webhookUrl,
         webhookSecret: this.config.webhookSecret,
@@ -514,6 +581,7 @@ class TaskExecutor {
         wireAdcpVersion: this.config.wireAdcpVersion,
         versionEnvelope: this.config.versionEnvelope
       });
+      let webhookRegistrationPersisted = false;
       if (webhookUrl && this.config.onWebhookRegistration) {
         const registration = webhookRegistrationFromPreparedCall(agent, preparedCall);
         if (registration) {
@@ -523,16 +591,35 @@ class TaskExecutor {
             operationId: taskId,
             ...registration
           });
+          webhookRegistrationPersisted = true;
         }
       }
       throwIfAborted(options.signal);
-      let dispatchCommitted = false;
       if (beforeProtocolDispatch) {
         let decision;
+        dispatchBoundaryOwnsTerminalState = true;
         try {
-          decision = await beforeProtocolDispatch(effectiveParams, { governanceAdjusted });
+          if (this.deferredTerminalPublicationTaskIds.size + this.settlementCapacityReservations.size >= COMPACTED_TASK_STATE_LIMIT) {
+            throw new Error("The durable task-settlement capacity is exhausted; no mutation claim was attempted.");
+          }
+          this.settlementCapacityReservations.add(taskId);
+          if (webhookRegistrationPersisted) {
+            await this.config.onDurableSettlementRequired?.(taskId);
+            throwIfAborted(options.signal);
+          }
+          decision = await beforeProtocolDispatch(dispatchParams, {
+            governanceAdjusted,
+            publishSettledTaskStatus: (status, data, error) => this.publishSettledTaskStatus(taskId, status, data, error),
+            registerExternalTaskSettlement: (handler) => this.registerExternalTaskSettlement(taskId, handler)
+          });
+          if (decision.action === "dispatch_committed") {
+            this.deferredTerminalPublicationTaskIds.add(taskId);
+            this.retainExternalTaskSettlementState(taskId);
+          }
         } catch (error) {
           throw new BeforeProtocolDispatchHookError(error);
+        } finally {
+          this.settlementCapacityReservations.delete(taskId);
         }
         if (decision.action === "return") {
           const earlyResult = decision.result;
@@ -542,7 +629,10 @@ class TaskExecutor {
           return attachMatch(earlyResult);
         }
         dispatchCommitted = true;
+        dispatchSettlement = decision;
       }
+      throwIfAborted(options.signal);
+      const postDispatchOptions = dispatchCommitted ? { ...options, signal: void 0 } : options;
       const callOptions = {
         debugLogs,
         webhookUrl,
@@ -553,12 +643,9 @@ class TaskExecutor {
         ...this.config.wireAdcpVersion !== void 0 && { wireAdcpVersion: this.config.wireAdcpVersion },
         ...this.config.versionEnvelope !== void 0 && { versionEnvelope: this.config.versionEnvelope },
         transport: options.transport ?? this.config.transport,
-        // Once a durable continuation claim commits, the seller call itself
-        // must cross the network boundary even if the caller's deadline fired
-        // while the atomic store operation was pending. The outer deadline
-        // still rejects promptly and post-call handling marks the outcome
-        // ambiguous for reconciliation.
-        signal: dispatchCommitted ? void 0 : options.signal,
+        // Once dispatch begins for a live committed claim, post-call handling
+        // owns durable settlement even if the caller's deadline fires later.
+        signal: postDispatchOptions.signal,
         onTransportActivity: this.config.onTransportActivity,
         transportActivityContext: {
           operationId: taskId,
@@ -568,10 +655,10 @@ class TaskExecutor {
         }
       };
       const response = await withPreparedProtocolToolCall(
-        { agent, toolName: taskName, args: effectiveParams, preparedCall },
-        () => ProtocolClient.callTool(agent, taskName, effectiveParams, callOptions)
+        { agent, toolName: taskName, args: dispatchParams, preparedCall },
+        () => ProtocolClient.callTool(agent, taskName, dispatchParams, callOptions)
       );
-      throwIfAborted(options.signal);
+      throwIfAborted(postDispatchOptions.signal);
       const respStatus = this.responseParser.getStatus(response);
       await this.config.onActivity?.({
         type: "protocol_response",
@@ -584,7 +671,7 @@ class TaskExecutor {
         payload: response,
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       });
-      throwIfAborted(options.signal);
+      throwIfAborted(postDispatchOptions.signal);
       const responseMessage = {
         id: randomUUID(),
         role: "agent",
@@ -593,22 +680,33 @@ class TaskExecutor {
         metadata: { toolName: taskName, type: "response" }
       };
       const messages = [initialMessage, responseMessage];
-      const result = await this.handleAsyncResponse(
+      let result = await this.handleAsyncResponse(
         agent,
         taskId,
         taskName,
-        effectiveParams,
+        dispatchParams,
         response,
         messages,
         inputHandler,
-        options,
+        postDispatchOptions,
         debugLogs,
-        startTime
+        startTime,
+        dispatchCommitted
       );
-      throwIfAborted(options.signal);
+      throwIfAborted(postDispatchOptions.signal);
       if (governanceResult) {
         result.governance = governanceResult;
       }
+      if (dispatchSettlement?.onResult) {
+        dispatchSettlementStarted = true;
+        try {
+          result = await dispatchSettlement.onResult(attachMatch(result));
+        } catch (error) {
+          this.closeExternalTaskSettlement(taskId, error);
+          this.updateTaskStatus(taskId, "failed", void 0, error instanceof Error ? error.message : String(error));
+          throw new AfterProtocolDispatchHookError(error);
+        }
+      }
       if (governanceCheckId && this.governanceMiddleware) {
         const govCtx = governanceResult?.governanceContext;
         if (result.status === "completed" && govCtx) {
@@ -628,10 +726,10 @@ class TaskExecutor {
             void 0,
             debugLogs,
             govCtx,
-            options.signal,
+            postDispatchOptions.signal,
             outcomeIdempotencyKey
           );
-          throwIfAborted(options.signal);
+          throwIfAborted(postDispatchOptions.signal);
           if (!result.governanceOutcome) {
             result.governanceOutcomeError = "Outcome reporting to governance agent failed";
           }
@@ -649,10 +747,10 @@ class TaskExecutor {
             { message: result.error },
             debugLogs,
             govCtx,
-            options.signal,
+            postDispatchOptions.signal,
             outcomeIdempotencyKey
           );
-          throwIfAborted(options.signal);
+          throwIfAborted(postDispatchOptions.signal);
           if (!result.governanceOutcome) {
             result.governanceOutcomeError = "Outcome reporting to governance agent failed";
           }
@@ -660,6 +758,12 @@ class TaskExecutor {
           result.governance = { ...result.governance ?? {}, checkId: governanceCheckId };
         }
       }
+      if (dispatchCommitted) {
+        result = this.attachSettledContinuationTaskStatus(taskId, result);
+        if (TERMINAL_TASK_STATUSES.has(result.status)) {
+          this.publishSettledTaskStatus(taskId, result.status, result.data, result.error);
+        }
+      }
       if (["completed", "failed", "rejected", "canceled", "governance-denied", "aborted"].includes(result.status) && this.activeTasks.get(taskId)?.status !== result.status) {
         this.updateTaskStatus(taskId, result.status, result.data, result.error);
       }
@@ -669,6 +773,22 @@ class TaskExecutor {
         this.updateTaskStatus(taskId, "failed", void 0, error.message);
         throw error;
       }
+      if (error instanceof AfterProtocolDispatchHookError) throw error;
+      if (dispatchCommitted && dispatchSettlement?.onError && !dispatchSettlementStarted) {
+        try {
+          await dispatchSettlement.onError(error);
+        } catch (settlementError) {
+          this.closeExternalTaskSettlement(taskId, settlementError);
+          this.updateTaskStatus(
+            taskId,
+            "failed",
+            void 0,
+            settlementError instanceof Error ? settlementError.message : String(settlementError)
+          );
+          throw new AfterProtocolDispatchHookError(settlementError);
+        }
+        this.closeExternalTaskSettlement(taskId, error);
+      }
       if (isAbortOrTimeoutError(error)) {
         if (idempotencyKey && error && typeof error === "object") {
           error.idempotency_key = idempotencyKey;
@@ -719,12 +839,12 @@ class TaskExecutor {
       debug_logs: debugLogs
     };
   }
-  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now()) {
+  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false) {
     const status = this.responseParser.getStatus(response);
     switch (status) {
       case ADCP_STATUS.COMPLETED:
         const completedData = this.extractResponseData(response, debugLogs, taskName);
-        this.updateTaskStatus(taskId, "completed", completedData);
+        if (!deferTerminalTaskStatus) this.updateTaskStatus(taskId, "completed", completedData);
         const operationSuccess = this.isOperationSuccess(completedData, taskName);
         const validationResult = this.validateResponseSchema(completedData, taskName, debugLogs);
         const finalSuccess = operationSuccess && validationResult.valid;
@@ -780,7 +900,17 @@ class TaskExecutor {
           startTime
         );
       case ADCP_STATUS.SUBMITTED:
-        return this.setupSubmittedTask(agent, taskId, taskName, response, messages, options, debugLogs, startTime);
+        return this.setupSubmittedTask(
+          agent,
+          taskId,
+          taskName,
+          response,
+          messages,
+          options,
+          debugLogs,
+          startTime,
+          deferTerminalTaskStatus
+        );
       case ADCP_STATUS.INPUT_REQUIRED:
         return this.handleInputRequired(
           agent,
@@ -792,7 +922,8 @@ class TaskExecutor {
           inputHandler,
           options,
           debugLogs,
-          startTime
+          startTime,
+          deferTerminalTaskStatus
         );
       case ADCP_STATUS.FAILED:
       case ADCP_STATUS.REJECTED:
@@ -994,7 +1125,7 @@ class TaskExecutor {
   /**
    * Set up submitted task with webhook
    */
-  async setupSubmittedTask(agent, taskId, taskName, response, messages, options = {}, debugLogs = [], startTime = Date.now()) {
+  async setupSubmittedTask(agent, taskId, taskName, response, messages, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false) {
     const partialData = this.extractResponseData(response, debugLogs, taskName);
     let webhookUrl = response.webhookUrl;
     if (!webhookUrl && this.config.webhookManager) {
@@ -1018,14 +1149,16 @@ class TaskExecutor {
       webhookUrl,
       track: async (transport) => {
         const task = await this.getTaskStatus(agent, serverTaskId, transport ?? pollingTransport);
-        if (["completed", "failed", "rejected", "canceled"].includes(task.status)) {
+        if (!deferTerminalTaskStatus && ["completed", "failed", "rejected", "canceled"].includes(task.status)) {
           this.updateTaskStatus(taskId, task.status, task.result, task.error);
         }
         return task;
       },
       waitForCompletion: async (pollInterval = 6e4, signal) => {
         const completed = await this.pollTaskCompletion(agent, serverTaskId, pollInterval, pollingTransport, signal);
-        this.updateTaskStatus(taskId, completed.status, completed.data, completed.error);
+        if (!deferTerminalTaskStatus || !TERMINAL_TASK_STATUSES.has(completed.status)) {
+          this.updateTaskStatus(taskId, completed.status, completed.data, completed.error);
+        }
         return completed;
       }
     };
@@ -1049,6 +1182,193 @@ class TaskExecutor {
       debug_logs: debugLogs
     };
   }
+  /**
+   * A committed compatibility hook may replace resumable continuations with
+   * wrappers that validate and durably persist their terminal result. Attach
+   * local task publication only after those final wrappers return.
+   */
+  attachSettledContinuationTaskStatus(taskId, result) {
+    const publish = (status, data, error) => {
+      this.publishSettledTaskStatus(taskId, status, data, error);
+    };
+    if (result.submitted) {
+      const submitted = result.submitted;
+      result.submitted = {
+        ...submitted,
+        track: async (transport) => {
+          const task = await submitted.track(transport);
+          publish(task.status, task.result, task.error);
+          return task;
+        },
+        waitForCompletion: async (pollInterval, signal) => {
+          const completion = this.attachSettledContinuationTaskStatus(
+            taskId,
+            await submitted.waitForCompletion(pollInterval, signal)
+          );
+          publish(completion.status, completion.data, completion.error);
+          return completion;
+        }
+      };
+    }
+    if (result.deferred) {
+      const deferred = result.deferred;
+      result.deferred = {
+        ...deferred,
+        resume: async (input) => {
+          const completion = this.attachSettledContinuationTaskStatus(taskId, await deferred.resume(input));
+          publish(completion.status, completion.data, completion.error);
+          return completion;
+        }
+      };
+    }
+    return result;
+  }
+  publishSettledTaskStatus(taskId, status, data, error, fromExternalObservation = false) {
+    if (!TERMINAL_TASK_STATUSES.has(status)) return;
+    const task = this.activeTasks.get(taskId);
+    if (!task) return;
+    if (!fromExternalObservation) {
+      this.closeExternalTaskSettlement(
+        taskId,
+        new Error("The task settled through its direct response; a racing pushed result was not accepted.")
+      );
+    }
+    if (task.status !== status) this.updateTaskStatus(taskId, status, data, error);
+  }
+  rejectPendingExternalTaskObservations(taskId, error) {
+    const pending = this.pendingExternalTaskObservations.get(taskId);
+    this.pendingExternalTaskObservations.delete(taskId);
+    for (const waiter of pending ?? []) waiter.reject(error);
+  }
+  closeExternalTaskSettlement(taskId, error) {
+    this.externalTaskSettlementHandlers.delete(taskId);
+    this.externalTaskSettlementInFlight.delete(taskId);
+    this.closedExternalTaskSettlementTaskIds.add(taskId);
+    this.rejectPendingExternalTaskObservations(taskId, error);
+  }
+  clearExternalTaskSettlementState(taskId) {
+    this.deferredTerminalPublicationTaskIds.delete(taskId);
+    this.closedExternalTaskSettlementTaskIds.delete(taskId);
+    this.externalTaskSettlementHandlers.delete(taskId);
+    this.externalTaskSettlementInFlight.delete(taskId);
+    this.settledExternalTaskObservationKeys.delete(taskId);
+    this.externalTaskSettlementExpiry.delete(taskId);
+    this.rejectPendingExternalTaskObservations(
+      taskId,
+      new Error("The durable push-settlement retention window expired before the observation was accepted.")
+    );
+  }
+  retainExternalTaskSettlementState(taskId) {
+    const retentionMs = this.config.externalTaskSettlementRetentionMs ?? DEFAULT_EXTERNAL_TASK_SETTLEMENT_RETENTION_MS;
+    const expiry = Date.now() + retentionMs;
+    if ((this.externalTaskSettlementExpiry.get(taskId) ?? 0) >= expiry) return;
+    this.externalTaskSettlementExpiry.set(taskId, expiry);
+    const expire = () => {
+      if (this.externalTaskSettlementExpiry.get(taskId) !== expiry) return;
+      const remaining = expiry - Date.now();
+      if (remaining > 0) {
+        const timer2 = setTimeout(expire, Math.min(remaining, MAX_TIMER_DELAY_MS));
+        timer2.unref?.();
+        return;
+      }
+      this.clearExternalTaskSettlementState(taskId);
+    };
+    const timer = setTimeout(expire, Math.min(retentionMs, MAX_TIMER_DELAY_MS));
+    timer.unref?.();
+  }
+  /** Release short-lived task inspection state without dropping a live durable push fence. */
+  cleanupTerminalTaskInspectionState(taskId) {
+    this.activeTasks.delete(taskId);
+    this.compactedTaskIds.delete(taskId);
+    if (this.deferredTerminalPublicationTaskIds.has(taskId) || this.closedExternalTaskSettlementTaskIds.has(taskId) || this.externalTaskSettlementHandlers.has(taskId)) {
+      if (this.externalTaskSettlementExpiry.has(taskId)) return;
+    }
+    this.clearExternalTaskSettlementState(taskId);
+  }
+  registerExternalTaskSettlement(taskId, handler) {
+    this.externalTaskSettlementHandlers.set(taskId, handler);
+    const pending = this.pendingExternalTaskObservations.get(taskId);
+    if (!pending) return;
+    this.pendingExternalTaskObservations.delete(taskId);
+    for (const waiter of pending) {
+      void this.settleExternalTaskStatus(taskId, handler, waiter.observation).then(waiter.resolve, waiter.reject);
+    }
+  }
+  externalTaskObservationKey(observation) {
+    return createHash("sha256").update(
+      canonicalize({
+        status: observation.status,
+        serverTaskId: observation.serverTaskId ?? null,
+        taskType: observation.taskType ?? null,
+        result: observation.result ?? null
+      })
+    ).digest("base64url");
+  }
+  async settleExternalTaskStatus(taskId, handler, observation) {
+    const observationKey = this.externalTaskObservationKey(observation);
+    const existing = this.externalTaskSettlementInFlight.get(taskId);
+    if (existing) {
+      if (existing.waiterCount >= MAX_PENDING_EXTERNAL_TASK_OBSERVATIONS) {
+        throw new Error("Too many terminal push notifications are undergoing durable task settlement.");
+      }
+      existing.waiterCount += 1;
+      try {
+        const accepted = await existing.settlement;
+        if (existing.observationKey !== observationKey) {
+          throw new Error("This task already completed durable settlement; the pushed result was not accepted.");
+        }
+        return { ...accepted, duplicate: true };
+      } finally {
+        existing.waiterCount -= 1;
+      }
+    }
+    const settlement = (async () => {
+      const settled = await handler(observation);
+      const settledStatus = settled.status;
+      if (this.closedExternalTaskSettlementTaskIds.has(taskId)) {
+        throw new Error("The task settled through its direct response; the racing pushed result was not accepted.");
+      }
+      if (this.settledExternalTaskObservationKeys.has(taskId)) {
+        throw new Error("This task already completed durable settlement; the pushed result was not accepted.");
+      }
+      this.publishSettledTaskStatus(taskId, settledStatus, settled.data, settled.error, true);
+      this.settledExternalTaskObservationKeys.set(taskId, {
+        key: observationKey,
+        status: settledStatus,
+        ...settled.error !== void 0 && {
+          error: settled.error.slice(0, MAX_RETAINED_EXTERNAL_TASK_ERROR_CHARS)
+        }
+      });
+      this.closeExternalTaskSettlement(
+        taskId,
+        new Error("The task already completed durable external settlement; a later pushed result was not accepted.")
+      );
+      return {
+        settled: true,
+        result: settled.data,
+        status: settled.status,
+        ...settled.error !== void 0 && { error: settled.error }
+      };
+    })();
+    const inFlight = { observationKey, settlement, waiterCount: 1 };
+    this.externalTaskSettlementInFlight.set(taskId, inFlight);
+    try {
+      return await settlement;
+    } finally {
+      if (this.externalTaskSettlementInFlight.get(taskId) === inFlight) {
+        this.externalTaskSettlementInFlight.delete(taskId);
+      }
+    }
+  }
+  /** Release abandoned caller data without publishing a premature terminal state. */
+  compactAbandonedObserverTaskState(taskId) {
+    const task = this.activeTasks.get(taskId);
+    if (!task) return;
+    task.params = void 0;
+    task.messages = [];
+    task.options = {};
+    delete task.pendingInput;
+  }
   /**
    * A working/submitted response carries everything needed to poll externally.
    * Keeping the original request in activeTasks after dispatch would pin
@@ -1067,10 +1387,14 @@ class TaskExecutor {
     this.compactedTaskIds.delete(taskId);
     this.compactedTaskIds.set(taskId, true);
     while (this.compactedTaskIds.size > COMPACTED_TASK_STATE_LIMIT) {
-      const oldest = this.compactedTaskIds.keys().next().value;
+      const oldest = [...this.compactedTaskIds.keys()].find(
+        (candidate) => !this.deferredTerminalPublicationTaskIds.has(candidate) && !this.externalTaskSettlementHandlers.has(candidate) && !this.externalTaskSettlementInFlight.has(candidate)
+      );
       if (oldest === void 0) break;
       this.compactedTaskIds.delete(oldest);
       this.activeTasks.delete(oldest);
+      this.closeExternalTaskSettlement(oldest, new Error("The compacted task was evicted before push settlement."));
+      this.closedExternalTaskSettlementTaskIds.delete(oldest);
     }
   }
   /**
@@ -1081,7 +1405,7 @@ class TaskExecutor {
    * This is common for HITL (human-in-the-loop) workflows where the agent has already processed
    * the request and is just signaling that async approval may be needed.
    */
-  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now()) {
+  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false) {
     const inputRequest = this.responseParser.parseInputRequest(response);
     if (!inputHandler) {
       const partialData = this.extractResponseData(response, debugLogs, taskName);
@@ -1159,7 +1483,7 @@ class TaskExecutor {
       const deferred = {
         token,
         question: inputRequest.question,
-        resume: (input) => this.resumeDeferredTask(token, input)
+        resume: (input) => this.resumeDeferredTask(token, input, !deferTerminalTaskStatus)
       };
       return {
         success: true,
@@ -1192,7 +1516,8 @@ class TaskExecutor {
       // Pass handler for multi-round clarification
       options,
       debugLogs,
-      startTime
+      startTime,
+      deferTerminalTaskStatus
     );
   }
   /**
@@ -1411,7 +1736,7 @@ class TaskExecutor {
   /**
    * Resume a deferred task (client deferral)
    */
-  async resumeDeferredTask(token, input) {
+  async resumeDeferredTask(token, input, publishTerminalTaskStatus = true) {
     if (!this.config.deferredStorage) {
       throw new Error("Deferred storage not configured");
     }
@@ -1428,11 +1753,15 @@ class TaskExecutor {
         state.contextId,
         input,
         state.messages,
-        void 0
+        void 0,
         // No handler for deferred tasks - input was provided by human
+        {},
+        [],
+        Date.now(),
+        !publishTerminalTaskStatus
       );
       const remainsPaused = ["input-required", "auth-required", "deferred"].includes(resumed.status);
-      if (["completed", "failed", "rejected", "canceled", "governance-denied", "aborted"].includes(resumed.status) && this.activeTasks.get(state.taskId)?.status !== resumed.status) {
+      if (publishTerminalTaskStatus && ["completed", "failed", "rejected", "canceled", "governance-denied", "aborted"].includes(resumed.status) && this.activeTasks.get(state.taskId)?.status !== resumed.status) {
         this.updateTaskStatus(state.taskId, resumed.status, resumed.data, resumed.error);
       }
       if (!remainsPaused) {
@@ -1440,7 +1769,14 @@ class TaskExecutor {
       }
       return attachMatch(resumed);
     } catch (error) {
-      this.updateTaskStatus(state.taskId, "failed", void 0, error instanceof Error ? error.message : String(error));
+      if (publishTerminalTaskStatus) {
+        this.updateTaskStatus(
+          state.taskId,
+          "failed",
+          void 0,
+          error instanceof Error ? error.message : String(error)
+        );
+      }
       try {
         await this.config.deferredStorage.delete(token);
       } catch {
@@ -1451,7 +1787,7 @@ class TaskExecutor {
   /**
    * Continue a task after receiving input
    */
-  async continueTaskWithInput(agent, taskId, taskName, params, contextId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now()) {
+  async continueTaskWithInput(agent, taskId, taskName, params, contextId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false) {
     const inputMessage = {
       id: randomUUID(),
       role: "user",
@@ -1501,7 +1837,8 @@ class TaskExecutor {
       inputHandler,
       options,
       debugLogs,
-      startTime
+      startTime,
+      deferTerminalTaskStatus
     );
   }
   /**
@@ -1786,8 +2123,7 @@ class TaskExecutor {
         task.options = {};
         delete task.pendingInput;
         setTimeout(() => {
-          this.activeTasks.delete(taskId);
-          this.compactedTaskIds.delete(taskId);
+          this.cleanupTerminalTaskInspectionState(taskId);
         }, 3e4).unref();
       }
     }
@@ -1800,6 +2136,7 @@ class TaskExecutor {
   }
 }
 export {
+  AfterProtocolDispatchHookError,
   BeforeProtocolDispatchHookError,
   DeferredTaskError,
   InputRequiredError,