@adcp/sdk 16.0.0-beta.9 → 16.1.0

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, DirectPauseRecoveryRequest, WebhookUrlTemplate } from './ConversationTypes';
+import type { Message, InputHandler, TaskOptions, TaskResult, TaskState, TaskStatus, TaskInfo, DirectPauseRecoveryRequest, TrackTaskRequest, TrackedTask, WebhookUrlTemplate } from './ConversationTypes';
 import type { Activity } from './AsyncHandler';
 import { GovernanceMiddleware } from './GovernanceMiddleware';
 import type { GovernanceConfig } from './GovernanceTypes';
@@ -279,6 +279,8 @@ export declare class TaskExecutor {
      * Set up submitted task with webhook
      */
     private setupSubmittedTask;
+    /** Rebuild the polling continuation for seller work persisted by the caller. */
+    trackTask<T = unknown>(agent: AgentConfig, request: TrackTaskRequest): TrackedTask<T>;
     /** Build polling closures around one authoritative seller work handle. */
     private createSubmittedContinuation;
     /**

package/dist/lib/core/TaskExecutor.js

@@ -636,6 +636,10 @@ class TaskExecutor {
    * @internal
    */
   async observeExternalTaskStatus(taskId, status, result, identity = {}) {
+    const task = this.activeTasks.get(taskId);
+    if (task && (identity.serverTaskId !== void 0 && task.serverTaskId !== void 0 && identity.serverTaskId !== task.serverTaskId || identity.taskType !== void 0 && identity.taskType !== task.taskName)) {
+      throw new import_errors2.ConfigurationError("The pushed task identity does not match the tracked operation.");
+    }
     if (!["completed", "failed", "rejected", "canceled", "governance-denied", "aborted"].includes(status)) {
       return { settled: false, result };
     }
@@ -664,7 +668,9 @@ class TaskExecutor {
       this.pendingExternalTaskObservations.set(taskId, pending);
       return { settled: false, queued: true };
     }
-    this.updateTaskStatus(taskId, status, result);
+    if (task && task.serverTaskId === void 0 && identity.serverTaskId !== void 0)
+      task.serverTaskId = identity.serverTaskId;
+    if (task && !TERMINAL_TASK_STATUSES.has(task.status)) this.updateTaskStatus(taskId, status, result);
     return { settled: false, result };
   }
   /** Whether this process can safely settle or reject a durable callback for the operation. */
@@ -792,6 +798,9 @@ class TaskExecutor {
       this.requireDeferredSettlementOperationRouting(this.config.deferredStorage, true);
     }
     const taskId = (0, import_task_deadline.getTaskOperationId)(options) ?? (0, import_crypto.randomUUID)();
+    if (this.activeTasks.has(taskId) || this.compactedTaskIds.has(taskId) || this.deferredTerminalPublicationTaskIds.has(taskId) || this.closedExternalTaskSettlementTaskIds.has(taskId) || this.externalTaskSettlementHandlers.has(taskId)) {
+      throw new import_errors2.ConfigurationError("operationId is already in use by this client; track the existing task instead.");
+    }
     const startTime = Date.now();
     const workingTimeout = this.config.workingTimeout || 12e4;
     const wireAdcpVersion = options.wireAdcpVersion ?? this.config.wireAdcpVersion;
@@ -1067,12 +1076,14 @@ class TaskExecutor {
       );
       (0, import_abort.throwIfAborted)(postDispatchOptions.signal);
       const respStatus = this.responseParser.getStatus(response);
+      taskState.serverTaskId = this.responseParser.getTaskId(response);
       await this.config.onActivity?.({
         type: "protocol_response",
         operation_id: taskId,
         agent_id: agent.id,
         context_id: options.contextId,
         task_id: taskId,
+        server_task_id: taskState.serverTaskId,
         task_type: taskName,
         status: respStatus,
         payload: response,
@@ -1247,6 +1258,9 @@ class TaskExecutor {
   }
   async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
     const status = this.responseParser.getStatus(response);
+    const serverTaskId = this.responseParser.getTaskId(response);
+    const task = this.activeTasks.get(taskId);
+    if (task && serverTaskId) task.serverTaskId = serverTaskId;
     switch (status) {
       case import_ProtocolResponseParser.ADCP_STATUS.COMPLETED:
         const completedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
@@ -1602,8 +1616,70 @@ class TaskExecutor {
       debug_logs: debugLogs
     };
   }
+  /** Rebuild the polling continuation for seller work persisted by the caller. */
+  trackTask(agent, request) {
+    if (typeof request.taskId !== "string" || !request.taskId.trim()) {
+      throw new TypeError("taskId must be a non-empty seller task id.");
+    }
+    if (typeof request.taskType !== "string" || !request.taskType.trim()) {
+      throw new TypeError("taskType must be a non-empty tool name.");
+    }
+    const operationId = (0, import_task_deadline.getTaskOperationId)(request) ?? (0, import_crypto.randomUUID)();
+    const existing = this.activeTasks.get(operationId);
+    if (existing && (existing.serverTaskId !== request.taskId || existing.taskName !== request.taskType || existing.agent.id !== agent.id || existing.agent.protocol !== agent.protocol || existing.status === "pending")) {
+      throw new import_errors2.ConfigurationError(
+        "operationId is already tracked by this client for a different or dispatching task."
+      );
+    }
+    if (this.deferredTerminalPublicationTaskIds.has(operationId) || this.closedExternalTaskSettlementTaskIds.has(operationId) || this.externalTaskSettlementHandlers.has(operationId)) {
+      throw new import_errors2.ConfigurationError("This operation requires its original continuation or durable settlement recovery.");
+    }
+    const startTime = existing?.startTime ?? Date.now();
+    if (!existing)
+      this.activeTasks.set(operationId, {
+        taskId: operationId,
+        serverTaskId: request.taskId,
+        taskName: request.taskType,
+        status: "submitted",
+        messages: [],
+        startTime,
+        attempt: 0,
+        maxAttempts: 0,
+        options: {},
+        agent: { id: agent.id, name: agent.name, protocol: agent.protocol },
+        serverVersion: "v3"
+      });
+    if (!existing) this.compactIntermediateTaskState(operationId, "submitted");
+    const continuation = this.createSubmittedContinuation(
+      agent,
+      operationId,
+      request.taskType,
+      request.taskId,
+      void 0,
+      snapshotTransportOptions(request.transport ?? this.config.transport),
+      {
+        ...this.buildMetadata({
+          taskId: operationId,
+          taskName: request.taskType,
+          agent,
+          startTime,
+          status: "submitted"
+        }),
+        serverTaskId: request.taskId,
+        a2aTaskId: request.cancelOnAbort === true ? request.a2aTaskId : void 0
+      },
+      false,
+      "v3",
+      this.config.wireAdcpVersion,
+      this.config.versionEnvelope,
+      request.signal
+    );
+    return { ...continuation, operationId };
+  }
   /** Build polling closures around one authoritative seller work handle. */
-  createSubmittedContinuation(agent, taskId, taskName, serverTaskId, webhookUrl, pollingTransport, metadata, deferTerminalTaskStatus, serverVersion, wireAdcpVersion, versionEnvelope) {
+  createSubmittedContinuation(agent, taskId, taskName, serverTaskId, webhookUrl, pollingTransport, metadata, deferTerminalTaskStatus, serverVersion, wireAdcpVersion, versionEnvelope, pollingSignal) {
+    const registeredTask = this.activeTasks.get(taskId);
+    const canPublish = (status) => registeredTask !== void 0 && this.activeTasks.get(taskId) === registeredTask && !TERMINAL_TASK_STATUSES.has(registeredTask.status) && registeredTask.status !== status;
     return {
       taskId: serverTaskId,
       webhookUrl,
@@ -1613,25 +1689,27 @@ class TaskExecutor {
           agent,
           serverTaskId,
           transportSnapshot,
-          void 0,
+          pollingSignal,
           taskName,
           serverVersion,
           wireAdcpVersion,
-          versionEnvelope
+          versionEnvelope,
+          taskId
         )).task;
-        if (!deferTerminalTaskStatus && ["completed", "failed", "rejected", "canceled"].includes(task.status)) {
+        if (!deferTerminalTaskStatus && ["completed", "failed", "rejected", "canceled"].includes(task.status) && canPublish(task.status)) {
           this.updateTaskStatus(taskId, task.status, task.result, task.error);
         }
-        return task;
+        return { ...task, operationId: taskId, serverTaskId };
       },
       waitForCompletion: async (pollInterval = 6e4, signal, requireExactTaskIdentity = false) => {
         void requireExactTaskIdentity;
+        const completionSignal = pollingSignal && signal ? AbortSignal.any([pollingSignal, signal]) : signal ?? pollingSignal;
         const completed = await this.pollTaskCompletion(
           agent,
           serverTaskId,
           pollInterval,
           pollingTransport,
-          signal,
+          completionSignal,
           metadata.a2aTaskId,
           taskName,
           taskId,
@@ -1639,7 +1717,9 @@ class TaskExecutor {
           wireAdcpVersion,
           versionEnvelope
         );
-        if (!deferTerminalTaskStatus || !TERMINAL_TASK_STATUSES.has(completed.status)) {
+        if ((!deferTerminalTaskStatus || !TERMINAL_TASK_STATUSES.has(completed.status)) && // Cancellation, identity mismatches, missing tasks, and malformed
+        // responses establish observation failure, not seller task failure.
+        (!TERMINAL_TASK_STATUSES.has(completed.status) || isAuthoritativePolledTerminal(completed)) && canPublish(completed.status)) {
           this.updateTaskStatus(taskId, completed.status, completed.data, completed.error);
         }
         return completed;
@@ -1652,7 +1732,9 @@ class TaskExecutor {
    * local task publication only after those final wrappers return.
    */
   attachSettledContinuationTaskStatus(taskId, result) {
+    const registeredTask = this.activeTasks.get(taskId);
     const publish = (status, data, error, identity) => {
+      if (registeredTask === void 0 || this.activeTasks.get(taskId) !== registeredTask) return;
       this.publishSettledTaskStatus(taskId, status, data, error, false, identity);
     };
     if (result.submitted) {
@@ -2283,7 +2365,7 @@ class TaskExecutor {
       return [];
     }
   }
-  async getTaskStatusWithRawResponse(agent, taskId, transport, signal, expectedTaskType, serverVersion, wireAdcpVersion, versionEnvelope) {
+  async getTaskStatusWithRawResponse(agent, taskId, transport, signal, expectedTaskType, serverVersion, wireAdcpVersion, versionEnvelope, operationId) {
     const toolName = agent.protocol === "mcp" ? "tasks_get" : "tasks/get";
     const response = await import_protocols.ProtocolClient.callTool(
       agent,
@@ -2302,7 +2384,8 @@ class TaskExecutor {
         signal,
         onTransportActivity: this.config.onTransportActivity,
         transportActivityContext: {
-          taskId
+          taskId,
+          ...operationId !== void 0 && { operationId }
         }
       }
     );
@@ -2334,12 +2417,13 @@ class TaskExecutor {
       wireOptions?.versionEnvelope
     )).task;
   }
-  async pollTaskCompletion(agent, taskId, pollInterval = 6e4, transport, signal, a2aCancellationTaskId, expectedTaskType, metadataTaskId = taskId, serverVersion, wireAdcpVersion, versionEnvelope) {
+  async pollTaskCompletion(agent, taskId, pollInterval = 6e4, transport, signal, a2aCancellationTaskId, expectedTaskType, metadataTaskId, serverVersion, wireAdcpVersion, versionEnvelope) {
     const transportSnapshot = snapshotTransportOptions(transport ?? this.config.transport);
     if (!Number.isFinite(pollInterval) || pollInterval < 0 || pollInterval > MAX_TIMER_DELAY_MS) {
       throw new RangeError(`pollInterval must be a finite non-negative number <= ${MAX_TIMER_DELAY_MS}`);
     }
     const pollStartTime = Date.now();
+    const correlationId = metadataTaskId ?? taskId;
     const withServerTaskId = (metadata) => ({
       ...metadata,
       serverTaskId: taskId
@@ -2367,8 +2451,8 @@ class TaskExecutor {
           error: `tasks/get polling was cancelled before a terminal state was observed: ${reason}`,
           metadata: withServerTaskId(
             this.buildMetadata({
-              taskId: metadataTaskId,
-              taskName: "unknown",
+              taskId: correlationId,
+              taskName: expectedTaskType ?? "unknown",
               agent,
               startTime: pollStartTime,
               status: "failed"
@@ -2387,11 +2471,15 @@ class TaskExecutor {
           expectedTaskType,
           serverVersion,
           wireAdcpVersion,
-          versionEnvelope
+          versionEnvelope,
+          metadataTaskId
         );
         status = pollResult.task;
         rawResponse = pollResult.rawResponse;
       } catch (err) {
+        if (signal?.aborted && agent.protocol === "a2a" && a2aCancellationTaskId && (0, import_abort.isAbortOrTimeoutError)(err)) {
+          continue;
+        }
         if (err instanceof TaskBindingMismatchError) {
           return (0, import_match.attachMatch)({
             success: false,
@@ -2399,8 +2487,8 @@ class TaskExecutor {
             error: err.message,
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
-                taskName: "unknown",
+                taskId: correlationId,
+                taskName: expectedTaskType ?? "unknown",
                 agent,
                 startTime: pollStartTime,
                 status: "failed",
@@ -2417,8 +2505,8 @@ class TaskExecutor {
             error: `Task ${taskId} is no longer queryable \u2014 it may have been completed and evicted by the seller before this poll arrived. Consider using push notifications (reporting_webhook) instead of polling, or configuring a longer task retention TTL on the seller.`,
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
-                taskName: "unknown",
+                taskId: correlationId,
+                taskName: expectedTaskType ?? "unknown",
                 agent,
                 startTime: pollStartTime,
                 status: "failed"
@@ -2433,13 +2521,15 @@ class TaskExecutor {
           success: false,
           status: "failed",
           error: "The seller returned a task outside the requested durable task identity.",
-          metadata: this.buildMetadata({
-            taskId,
-            taskName: "unknown",
-            agent,
-            startTime: pollStartTime,
-            status: "failed"
-          })
+          metadata: withServerTaskId(
+            this.buildMetadata({
+              taskId: correlationId,
+              taskName: expectedTaskType ?? "unknown",
+              agent,
+              startTime: pollStartTime,
+              status: "failed"
+            })
+          )
         });
       }
       if (status.status === import_ProtocolResponseParser.ADCP_STATUS.COMPLETED) {
@@ -2452,7 +2542,7 @@ class TaskExecutor {
               data: status.result,
               metadata: withServerTaskId(
                 this.buildMetadata({
-                  taskId: metadataTaskId,
+                  taskId: correlationId,
                   taskName: status.taskType,
                   agent,
                   responseTimeMs: Date.now() - status.createdAt,
@@ -2471,11 +2561,11 @@ class TaskExecutor {
             data: status.result,
             error: this.extractOperationError(status.result),
             adcpError: asyncResultErr,
-            errorInstance: this.buildErrorInstance(metadataTaskId, asyncResultErr),
+            errorInstance: this.buildErrorInstance(correlationId, asyncResultErr),
             correlationId: (0, import_error_extraction.extractCorrelationId)(status.result),
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
+                taskId: correlationId,
                 taskName: status.taskType,
                 agent,
                 responseTimeMs: Date.now() - status.createdAt,
@@ -2495,11 +2585,11 @@ class TaskExecutor {
             data: status.result,
             error: status.error || status.message || `Task ${status.status}`,
             adcpError: asyncFailedErr,
-            errorInstance: this.buildErrorInstance(metadataTaskId, asyncFailedErr),
+            errorInstance: this.buildErrorInstance(correlationId, asyncFailedErr),
             correlationId: (0, import_error_extraction.extractCorrelationId)(status.result),
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
+                taskId: correlationId,
                 taskName: status.taskType,
                 agent,
                 responseTimeMs: Date.now() - status.createdAt,
@@ -2517,7 +2607,7 @@ class TaskExecutor {
           data: status.result,
           metadata: withServerTaskId(
             this.buildMetadata({
-              taskId: metadataTaskId,
+              taskId: correlationId,
               taskName: status.taskType,
               agent,
               responseTimeMs: Date.now() - status.createdAt,
@@ -2534,8 +2624,8 @@ class TaskExecutor {
           error: `tasks/get returned an unrecognizable response (parsed status: "unknown", taskId: "${status.taskId}"). The seller may not implement tasks/get as an AdCP skill, or its response did not match any supported envelope shape (flat AdCP, MCP structuredContent, or A2A DataPart artifact).`,
           metadata: withServerTaskId(
             this.buildMetadata({
-              taskId: metadataTaskId,
-              taskName: "unknown",
+              taskId: correlationId,
+              taskName: expectedTaskType ?? "unknown",
               agent,
               startTime: pollStartTime,
               status: "failed",
@@ -4519,6 +4609,8 @@ class TaskExecutor {
       task.status = status;
       const taskInfo = {
         taskId: task.taskId,
+        operationId: task.taskId,
+        serverTaskId: task.serverTaskId,
         status,
         taskType: task.taskName,
         createdAt: task.startTime,
@@ -4533,6 +4625,7 @@ class TaskExecutor {
         agent_id: task.agent.id,
         context_id: void 0,
         task_id: task.taskId,
+        server_task_id: task.serverTaskId,
         task_type: task.taskName,
         status,
         payload: result ?? (error ? { error } : void 0),
@@ -4547,7 +4640,7 @@ class TaskExecutor {
         task.options = {};
         delete task.pendingInput;
         setTimeout(() => {
-          this.cleanupTerminalTaskInspectionState(taskId);
+          if (this.activeTasks.get(taskId) === task) this.cleanupTerminalTaskInspectionState(taskId);
         }, 3e4).unref();
       }
     }