@adcp/sdk 16.0.0 → 16.2.0

package/dist/lib/core/TaskExecutor.mjs

@@ -614,6 +614,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 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 };
     }
@@ -642,7 +646,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. */
@@ -770,6 +776,9 @@ class TaskExecutor {
       this.requireDeferredSettlementOperationRouting(this.config.deferredStorage, true);
     }
     const taskId = getTaskOperationId(options) ?? randomUUID();
+    if (this.activeTasks.has(taskId) || this.compactedTaskIds.has(taskId) || this.deferredTerminalPublicationTaskIds.has(taskId) || this.closedExternalTaskSettlementTaskIds.has(taskId) || this.externalTaskSettlementHandlers.has(taskId)) {
+      throw new 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;
@@ -1045,12 +1054,14 @@ class TaskExecutor {
       );
       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,
@@ -1225,6 +1236,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 ADCP_STATUS.COMPLETED:
         const completedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
@@ -1580,8 +1594,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 = getTaskOperationId(request) ?? 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 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 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,
@@ -1591,25 +1667,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,
@@ -1617,7 +1695,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;
@@ -1630,7 +1710,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) {
@@ -2261,7 +2343,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 ProtocolClient.callTool(
       agent,
@@ -2280,7 +2362,8 @@ class TaskExecutor {
         signal,
         onTransportActivity: this.config.onTransportActivity,
         transportActivityContext: {
-          taskId
+          taskId,
+          ...operationId !== void 0 && { operationId }
         }
       }
     );
@@ -2312,12 +2395,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
@@ -2345,8 +2429,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"
@@ -2365,11 +2449,15 @@ class TaskExecutor {
           expectedTaskType,
           serverVersion,
           wireAdcpVersion,
-          versionEnvelope
+          versionEnvelope,
+          metadataTaskId
         );
         status = pollResult.task;
         rawResponse = pollResult.rawResponse;
       } catch (err) {
+        if (signal?.aborted && agent.protocol === "a2a" && a2aCancellationTaskId && isAbortOrTimeoutError(err)) {
+          continue;
+        }
         if (err instanceof TaskBindingMismatchError) {
           return attachMatch({
             success: false,
@@ -2377,8 +2465,8 @@ class TaskExecutor {
             error: err.message,
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
-                taskName: "unknown",
+                taskId: correlationId,
+                taskName: expectedTaskType ?? "unknown",
                 agent,
                 startTime: pollStartTime,
                 status: "failed",
@@ -2395,8 +2483,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"
@@ -2411,13 +2499,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 === ADCP_STATUS.COMPLETED) {
@@ -2430,7 +2520,7 @@ class TaskExecutor {
               data: status.result,
               metadata: withServerTaskId(
                 this.buildMetadata({
-                  taskId: metadataTaskId,
+                  taskId: correlationId,
                   taskName: status.taskType,
                   agent,
                   responseTimeMs: Date.now() - status.createdAt,
@@ -2449,11 +2539,11 @@ class TaskExecutor {
             data: status.result,
             error: this.extractOperationError(status.result),
             adcpError: asyncResultErr,
-            errorInstance: this.buildErrorInstance(metadataTaskId, asyncResultErr),
+            errorInstance: this.buildErrorInstance(correlationId, asyncResultErr),
             correlationId: extractCorrelationId(status.result),
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
+                taskId: correlationId,
                 taskName: status.taskType,
                 agent,
                 responseTimeMs: Date.now() - status.createdAt,
@@ -2473,11 +2563,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: extractCorrelationId(status.result),
             metadata: withServerTaskId(
               this.buildMetadata({
-                taskId: metadataTaskId,
+                taskId: correlationId,
                 taskName: status.taskType,
                 agent,
                 responseTimeMs: Date.now() - status.createdAt,
@@ -2495,7 +2585,7 @@ class TaskExecutor {
           data: status.result,
           metadata: withServerTaskId(
             this.buildMetadata({
-              taskId: metadataTaskId,
+              taskId: correlationId,
               taskName: status.taskType,
               agent,
               responseTimeMs: Date.now() - status.createdAt,
@@ -2512,8 +2602,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",
@@ -4497,6 +4587,8 @@ class TaskExecutor {
       task.status = status;
       const taskInfo = {
         taskId: task.taskId,
+        operationId: task.taskId,
+        serverTaskId: task.serverTaskId,
         status,
         taskType: task.taskName,
         createdAt: task.startTime,
@@ -4511,6 +4603,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),
@@ -4525,7 +4618,7 @@ class TaskExecutor {
         task.options = {};
         delete task.pendingInput;
         setTimeout(() => {
-          this.cleanupTerminalTaskInspectionState(taskId);
+          if (this.activeTasks.get(taskId) === task) this.cleanupTerminalTaskInspectionState(taskId);
         }, 3e4).unref();
       }
     }

package/dist/lib/core/task-deadline.d.mts

@@ -6,6 +6,8 @@ type DeadlineTaskOptions<TOptions extends TaskOptions = TaskOptions> = TOptions
     [TASK_OPERATION_ID]: string;
     [TASK_DEADLINE_ERROR]?: TaskTimeoutError;
 };
+/** Give a child dispatch its own correlation id while retaining the parent deadline and cancellation. */
+export declare function childTaskOptions(options?: TaskOptions): TaskOptions;
 export declare function getTaskOperationId(options: TaskOptions | undefined): string | undefined;
 export declare function attachTaskDeadlineIdempotencyKey(options: TaskOptions, idempotencyKey: string): void;
 export declare function attachTaskDeadlineGovernanceRecovery(options: TaskOptions, recovery: GovernanceOutcomeRecovery): void;

package/dist/lib/core/task-deadline.d.ts

@@ -6,6 +6,8 @@ type DeadlineTaskOptions<TOptions extends TaskOptions = TaskOptions> = TOptions
     [TASK_OPERATION_ID]: string;
     [TASK_DEADLINE_ERROR]?: TaskTimeoutError;
 };
+/** Give a child dispatch its own correlation id while retaining the parent deadline and cancellation. */
+export declare function childTaskOptions(options?: TaskOptions): TaskOptions;
 export declare function getTaskOperationId(options: TaskOptions | undefined): string | undefined;
 export declare function attachTaskDeadlineIdempotencyKey(options: TaskOptions, idempotencyKey: string): void;
 export declare function attachTaskDeadlineGovernanceRecovery(options: TaskOptions, recovery: GovernanceOutcomeRecovery): void;

package/dist/lib/core/task-deadline.js

@@ -20,6 +20,7 @@ var task_deadline_exports = {};
 __export(task_deadline_exports, {
   attachTaskDeadlineGovernanceRecovery: () => attachTaskDeadlineGovernanceRecovery,
   attachTaskDeadlineIdempotencyKey: () => attachTaskDeadlineIdempotencyKey,
+  childTaskOptions: () => childTaskOptions,
   getTaskOperationId: () => getTaskOperationId,
   withTaskDeadline: () => withTaskDeadline
 });
@@ -29,8 +30,24 @@ var import_errors = require('../errors/index.js');
 var import_abort = require('../protocols/abort.js');
 const TASK_OPERATION_ID = /* @__PURE__ */ Symbol("adcp.taskOperationId");
 const TASK_DEADLINE_ERROR = /* @__PURE__ */ Symbol("adcp.taskDeadlineError");
+function childTaskOptions(options) {
+  const child = { ...options };
+  delete child.operationId;
+  delete child[TASK_OPERATION_ID];
+  return child;
+}
 function getTaskOperationId(options) {
-  return options?.[TASK_OPERATION_ID];
+  const operationId = options?.operationId;
+  if (operationId !== void 0 && (typeof operationId !== "string" || !/^(?!\.+$)[A-Za-z0-9_.:-]{1,255}$/.test(operationId) || operationId.startsWith("delivery_route:"))) {
+    throw new TypeError(
+      "operationId must contain 1\u2013255 letters, digits, underscores, periods, colons, or hyphens; dot-only IDs and the delivery_route: prefix are reserved."
+    );
+  }
+  const internalId = options?.[TASK_OPERATION_ID];
+  if (internalId !== void 0 && operationId !== void 0 && internalId !== operationId) {
+    throw new TypeError("operationId does not match the operation already assigned to this call.");
+  }
+  return internalId ?? operationId;
 }
 function attachTaskDeadlineIdempotencyKey(options, idempotencyKey) {
   const error = options[TASK_DEADLINE_ERROR];
@@ -44,7 +61,7 @@ function attachTaskDeadlineGovernanceRecovery(options, recovery) {
 }
 async function withTaskDeadline(options, run) {
   const existing = options;
-  const taskId = existing?.[TASK_OPERATION_ID] ?? (0, import_node_crypto.randomUUID)();
+  const taskId = getTaskOperationId(existing) ?? (0, import_node_crypto.randomUUID)();
   const timeout = options?.timeout;
   const baseOptions = { ...options, timeout: void 0, [TASK_OPERATION_ID]: taskId };
   (0, import_abort.throwIfAborted)(options?.signal);
@@ -68,6 +85,7 @@ async function withTaskDeadline(options, run) {
 0 && (module.exports = {
   attachTaskDeadlineGovernanceRecovery,
   attachTaskDeadlineIdempotencyKey,
+  childTaskOptions,
   getTaskOperationId,
   withTaskDeadline
 });

package/dist/lib/core/task-deadline.mjs

@@ -3,8 +3,24 @@ import { TaskTimeoutError } from "../errors/index.mjs";
 import { MAX_TIMER_DELAY_MS, throwIfAborted, withAbortSignal } from "../protocols/abort.mjs";
 const TASK_OPERATION_ID = /* @__PURE__ */ Symbol("adcp.taskOperationId");
 const TASK_DEADLINE_ERROR = /* @__PURE__ */ Symbol("adcp.taskDeadlineError");
+function childTaskOptions(options) {
+  const child = { ...options };
+  delete child.operationId;
+  delete child[TASK_OPERATION_ID];
+  return child;
+}
 function getTaskOperationId(options) {
-  return options?.[TASK_OPERATION_ID];
+  const operationId = options?.operationId;
+  if (operationId !== void 0 && (typeof operationId !== "string" || !/^(?!\.+$)[A-Za-z0-9_.:-]{1,255}$/.test(operationId) || operationId.startsWith("delivery_route:"))) {
+    throw new TypeError(
+      "operationId must contain 1\u2013255 letters, digits, underscores, periods, colons, or hyphens; dot-only IDs and the delivery_route: prefix are reserved."
+    );
+  }
+  const internalId = options?.[TASK_OPERATION_ID];
+  if (internalId !== void 0 && operationId !== void 0 && internalId !== operationId) {
+    throw new TypeError("operationId does not match the operation already assigned to this call.");
+  }
+  return internalId ?? operationId;
 }
 function attachTaskDeadlineIdempotencyKey(options, idempotencyKey) {
   const error = options[TASK_DEADLINE_ERROR];
@@ -18,7 +34,7 @@ function attachTaskDeadlineGovernanceRecovery(options, recovery) {
 }
 async function withTaskDeadline(options, run) {
   const existing = options;
-  const taskId = existing?.[TASK_OPERATION_ID] ?? randomUUID();
+  const taskId = getTaskOperationId(existing) ?? randomUUID();
   const timeout = options?.timeout;
   const baseOptions = { ...options, timeout: void 0, [TASK_OPERATION_ID]: taskId };
   throwIfAborted(options?.signal);
@@ -41,6 +57,7 @@ async function withTaskDeadline(options, run) {
 export {
   attachTaskDeadlineGovernanceRecovery,
   attachTaskDeadlineIdempotencyKey,
+  childTaskOptions,
   getTaskOperationId,
   withTaskDeadline
 };

package/dist/lib/governance/authorization.d.mts

@@ -12,7 +12,9 @@ import type { CheckGovernanceRequest, GovernancePhase, PlannedDelivery } from '.
 import type { JwksResolver } from '../signing/jwks.mjs';
 import type { ReplayStore } from '../signing/replay.mjs';
 import type { RevocationStore } from '../signing/revocation.mjs';
+import type { RevocationDetail } from '../identity-3.3/types.mjs';
 import { type HttpsJwksResolverOptions } from '../signing/jwks-https.mjs';
+import { type GovernanceKeyArchiveResolver, type JwsArtifactWebBotAuthOptions } from '../identity-3.3/jws-artifacts.mjs';
 export declare const GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS: readonly ["authorized_commitment", "authorized_task", "authorized_payload_hash"];
 export type GovernanceAuthorizationCriticalClaim = (typeof GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS)[number];
 export type GovernanceEnforcementMode = 'signed_context' | 'online_execution_check';
@@ -51,6 +53,12 @@ export interface GovernanceAuthorizationFailure {
     ok: false;
     error: GovernanceAuthorizationErrorCode;
     message: string;
+    /**
+     * Set when the failure is an outage (an issuer trust record, key directory,
+     * archive or revocation list could not be read), not a verdict on the
+     * token: the same token may verify on retry.
+     */
+    retryable?: true;
 }
 export type GovernanceAuthorizationResult = GovernanceAuthorizationSuccess | GovernanceAuthorizationFailure;
 export interface GovernanceReplayStore {
@@ -127,6 +135,18 @@ export interface VerifyGovernanceAuthorizationOptions {
     jwks?: JwksResolver;
     /** When supplied, discover keys from this exact authenticated buyer record. */
     buyerIdentity?: GovernanceBuyerIdentity;
+    /**
+     * AdCP 3.3 (`specs/agent-identity-3-3.md` R4): when the trust record derived
+     * from the issuer's origin lists that origin, verify the token with a key
+     * from the origin's Web Bot Auth key directory (`alg` `EdDSA`, `kid` the
+     * key's JWK thumbprint, no `use`/`key_ops`/`adcp_use` checks) and check
+     * revocation against the origin's list, never under the 3.2 profile. A
+     * trust-record fetch failure rejects the token; it never falls back to 3.2.
+     * An issuer no trust record lists stays on the 3.2 profile (`jwks` or
+     * `buyerIdentity`). Every other check is unchanged, including the
+     * `buyerIdentity` cross-check that the issuer is the buyer's governance agent.
+     */
+    webBotAuth?: JwsArtifactWebBotAuthOptions;
     replayStore: GovernanceReplayStore;
     /** Optional governance-key revocation source. */
     revocationStore?: RevocationStore;
@@ -187,6 +207,52 @@ export declare function targetDeclaresGovernanceEnforcement(capabilities: unknow
 export declare function targetDeclaresLegacyGovernanceAwareness(capabilities: unknown, task: string): boolean;
 /** Verify the published compact-JWS authorization profile and all service bindings. */
 export declare function verifyGovernanceAuthorization(options: VerifyGovernanceAuthorizationOptions): Promise<GovernanceAuthorizationResult>;
+export interface VerifyHistoricalGovernanceContextOptions {
+    token: unknown;
+    /** The governance agent the verifier expected to sign, from its own records. */
+    expectedIssuer: string;
+    /**
+     * The WBA components plus the governance key archive at the issuer's
+     * origin (`{origin}/.well-known/jwks-archive.json`, `security.mdx`
+     * §Revocation), which holds keys rotated out of the directory.
+     */
+    webBotAuth: JwsArtifactWebBotAuthOptions & {
+        archive: GovernanceKeyArchiveResolver;
+    };
+}
+export type HistoricalGovernanceContextResult = {
+    ok: true;
+    claims: GovernanceAuthorizationClaims;
+    protectedHeader: Record<string, unknown>;
+    /** The key was in the issuer's current directory, or only in its archive. */
+    keySource: 'directory' | 'archive';
+    /**
+     * The issuer origin's revocation status for the signing key: `current`
+     * (listed, not revoked), `absent` (the origin serves no list) or
+     * `revoked`. Online verification rejects every token a revoked key
+     * signed; an audit decides what a revocation means for a retained token
+     * from its detail (R9: only `keyCompromise` exposes, from its
+     * `invalidity_date`).
+     */
+    revocation: 'current' | 'absent' | 'revoked';
+    revocationDetail?: RevocationDetail;
+} | (GovernanceAuthorizationFailure & {
+    /** Set when the issuer is on the 3.2 profile, which this function does not verify. */
+    profile?: '3.2';
+});
+/**
+ * Historical (audit) verification of a retained governance context from a
+ * Web Bot Auth identity (R4): the key comes from the issuer origin's key
+ * directory or, once rotated out, from its governance key archive. Checks the
+ * token's shape, `typ`, `crit`, issuer, `alg` `EdDSA`, `kid` thumbprint and
+ * signature, and reports the origin's revocation status and detail for the
+ * key instead of rejecting a revoked one. It does not check expiry, audience,
+ * replay or the request binding, which only an online verification can.
+ *
+ * Profile selection is the same as online: an issuer whose origin no trust
+ * record lists is on the 3.2 profile, reported as `profile: '3.2'`.
+ */
+export declare function verifyHistoricalGovernanceContext(options: VerifyHistoricalGovernanceContextOptions): Promise<HistoricalGovernanceContextResult>;
 export declare class GovernanceAuthorizationError extends Error {
     readonly code: GovernanceAuthorizationErrorCode;
     constructor(result: GovernanceAuthorizationFailure);

package/dist/lib/governance/authorization.d.ts

@@ -12,7 +12,9 @@ import type { CheckGovernanceRequest, GovernancePhase, PlannedDelivery } from '.
 import type { JwksResolver } from '../signing/jwks';
 import type { ReplayStore } from '../signing/replay';
 import type { RevocationStore } from '../signing/revocation';
+import type { RevocationDetail } from '../identity-3.3/types';
 import { type HttpsJwksResolverOptions } from '../signing/jwks-https';
+import { type GovernanceKeyArchiveResolver, type JwsArtifactWebBotAuthOptions } from '../identity-3.3/jws-artifacts';
 export declare const GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS: readonly ["authorized_commitment", "authorized_task", "authorized_payload_hash"];
 export type GovernanceAuthorizationCriticalClaim = (typeof GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS)[number];
 export type GovernanceEnforcementMode = 'signed_context' | 'online_execution_check';
@@ -51,6 +53,12 @@ export interface GovernanceAuthorizationFailure {
     ok: false;
     error: GovernanceAuthorizationErrorCode;
     message: string;
+    /**
+     * Set when the failure is an outage (an issuer trust record, key directory,
+     * archive or revocation list could not be read), not a verdict on the
+     * token: the same token may verify on retry.
+     */
+    retryable?: true;
 }
 export type GovernanceAuthorizationResult = GovernanceAuthorizationSuccess | GovernanceAuthorizationFailure;
 export interface GovernanceReplayStore {
@@ -127,6 +135,18 @@ export interface VerifyGovernanceAuthorizationOptions {
     jwks?: JwksResolver;
     /** When supplied, discover keys from this exact authenticated buyer record. */
     buyerIdentity?: GovernanceBuyerIdentity;
+    /**
+     * AdCP 3.3 (`specs/agent-identity-3-3.md` R4): when the trust record derived
+     * from the issuer's origin lists that origin, verify the token with a key
+     * from the origin's Web Bot Auth key directory (`alg` `EdDSA`, `kid` the
+     * key's JWK thumbprint, no `use`/`key_ops`/`adcp_use` checks) and check
+     * revocation against the origin's list, never under the 3.2 profile. A
+     * trust-record fetch failure rejects the token; it never falls back to 3.2.
+     * An issuer no trust record lists stays on the 3.2 profile (`jwks` or
+     * `buyerIdentity`). Every other check is unchanged, including the
+     * `buyerIdentity` cross-check that the issuer is the buyer's governance agent.
+     */
+    webBotAuth?: JwsArtifactWebBotAuthOptions;
     replayStore: GovernanceReplayStore;
     /** Optional governance-key revocation source. */
     revocationStore?: RevocationStore;
@@ -187,6 +207,52 @@ export declare function targetDeclaresGovernanceEnforcement(capabilities: unknow
 export declare function targetDeclaresLegacyGovernanceAwareness(capabilities: unknown, task: string): boolean;
 /** Verify the published compact-JWS authorization profile and all service bindings. */
 export declare function verifyGovernanceAuthorization(options: VerifyGovernanceAuthorizationOptions): Promise<GovernanceAuthorizationResult>;
+export interface VerifyHistoricalGovernanceContextOptions {
+    token: unknown;
+    /** The governance agent the verifier expected to sign, from its own records. */
+    expectedIssuer: string;
+    /**
+     * The WBA components plus the governance key archive at the issuer's
+     * origin (`{origin}/.well-known/jwks-archive.json`, `security.mdx`
+     * §Revocation), which holds keys rotated out of the directory.
+     */
+    webBotAuth: JwsArtifactWebBotAuthOptions & {
+        archive: GovernanceKeyArchiveResolver;
+    };
+}
+export type HistoricalGovernanceContextResult = {
+    ok: true;
+    claims: GovernanceAuthorizationClaims;
+    protectedHeader: Record<string, unknown>;
+    /** The key was in the issuer's current directory, or only in its archive. */
+    keySource: 'directory' | 'archive';
+    /**
+     * The issuer origin's revocation status for the signing key: `current`
+     * (listed, not revoked), `absent` (the origin serves no list) or
+     * `revoked`. Online verification rejects every token a revoked key
+     * signed; an audit decides what a revocation means for a retained token
+     * from its detail (R9: only `keyCompromise` exposes, from its
+     * `invalidity_date`).
+     */
+    revocation: 'current' | 'absent' | 'revoked';
+    revocationDetail?: RevocationDetail;
+} | (GovernanceAuthorizationFailure & {
+    /** Set when the issuer is on the 3.2 profile, which this function does not verify. */
+    profile?: '3.2';
+});
+/**
+ * Historical (audit) verification of a retained governance context from a
+ * Web Bot Auth identity (R4): the key comes from the issuer origin's key
+ * directory or, once rotated out, from its governance key archive. Checks the
+ * token's shape, `typ`, `crit`, issuer, `alg` `EdDSA`, `kid` thumbprint and
+ * signature, and reports the origin's revocation status and detail for the
+ * key instead of rejecting a revoked one. It does not check expiry, audience,
+ * replay or the request binding, which only an online verification can.
+ *
+ * Profile selection is the same as online: an issuer whose origin no trust
+ * record lists is on the 3.2 profile, reported as `profile: '3.2'`.
+ */
+export declare function verifyHistoricalGovernanceContext(options: VerifyHistoricalGovernanceContextOptions): Promise<HistoricalGovernanceContextResult>;
 export declare class GovernanceAuthorizationError extends Error {
     readonly code: GovernanceAuthorizationErrorCode;
     constructor(result: GovernanceAuthorizationFailure);