agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2a/jsonrpc/methods.js

@@ -0,0 +1,249 @@
+/**
+ * A2A Protocol Method Definitions
+ *
+ * Defines all A2A JSON-RPC methods, their parameters, and return types.
+ * Methods follow the A2A v0.3 specification.
+ *
+ * @module adapters/a2a/jsonrpc/methods
+ * @see https://a2a-protocol.org/latest/specification/
+ */
+// ============================================================================
+// Method Names
+// ============================================================================
+/**
+ * A2A method names as defined in the specification.
+ */
+export const A2A_METHODS = {
+    // Messaging methods
+    /** Send a message to the agent and receive a complete response. */
+    MESSAGE_SEND: 'message/send',
+    /** Send a message to the agent and stream responses via SSE. */
+    MESSAGE_STREAM: 'message/stream',
+    // Task management methods
+    /** Get task status and artifacts by ID. */
+    TASKS_GET: 'tasks/get',
+    /** List tasks with optional filtering. */
+    TASKS_LIST: 'tasks/list',
+    /** Cancel a running task. */
+    TASKS_CANCEL: 'tasks/cancel',
+    /** Resubmit a failed or canceled task. */
+    TASKS_RESUBMIT: 'tasks/resubmit',
+    // Push notification methods
+    /** Configure push notification settings for a task. */
+    TASKS_PUSH_NOTIFICATION_SET: 'tasks/pushNotification/set',
+    /** Get current push notification configuration. */
+    TASKS_PUSH_NOTIFICATION_GET: 'tasks/pushNotification/get',
+};
+/**
+ * Method descriptions for documentation and validation.
+ */
+export const A2A_METHOD_DESCRIPTIONS = {
+    [A2A_METHODS.MESSAGE_SEND]: 'Send a message to the agent and receive a complete response',
+    [A2A_METHODS.MESSAGE_STREAM]: 'Send a message to the agent and stream responses via SSE',
+    [A2A_METHODS.TASKS_GET]: 'Get task status and artifacts by ID',
+    [A2A_METHODS.TASKS_LIST]: 'List tasks with optional filtering',
+    [A2A_METHODS.TASKS_CANCEL]: 'Cancel a running task',
+    [A2A_METHODS.TASKS_RESUBMIT]: 'Resubmit a failed or canceled task',
+    [A2A_METHODS.TASKS_PUSH_NOTIFICATION_SET]: 'Configure push notification settings for a task',
+    [A2A_METHODS.TASKS_PUSH_NOTIFICATION_GET]: 'Get current push notification configuration',
+};
+/**
+ * Terminal task statuses (task cannot change from these).
+ */
+export const TERMINAL_STATUSES = ['completed', 'failed', 'canceled', 'rejected'];
+/**
+ * Complete method metadata registry.
+ */
+export const METHOD_METADATA = {
+    [A2A_METHODS.MESSAGE_SEND]: {
+        name: A2A_METHODS.MESSAGE_SEND,
+        description: A2A_METHOD_DESCRIPTIONS[A2A_METHODS.MESSAGE_SEND],
+        paramsRequired: true,
+        streaming: false,
+        authRequired: false,
+    },
+    [A2A_METHODS.MESSAGE_STREAM]: {
+        name: A2A_METHODS.MESSAGE_STREAM,
+        description: A2A_METHOD_DESCRIPTIONS[A2A_METHODS.MESSAGE_STREAM],
+        paramsRequired: true,
+        streaming: true,
+        authRequired: false,
+        requiredCapabilities: ['streaming'],
+    },
+    [A2A_METHODS.TASKS_GET]: {
+        name: A2A_METHODS.TASKS_GET,
+        description: A2A_METHOD_DESCRIPTIONS[A2A_METHODS.TASKS_GET],
+        paramsRequired: true,
+        streaming: false,
+        authRequired: false,
+    },
+    [A2A_METHODS.TASKS_LIST]: {
+        name: A2A_METHODS.TASKS_LIST,
+        description: A2A_METHOD_DESCRIPTIONS[A2A_METHODS.TASKS_LIST],
+        paramsRequired: false,
+        streaming: false,
+        authRequired: false,
+    },
+    [A2A_METHODS.TASKS_CANCEL]: {
+        name: A2A_METHODS.TASKS_CANCEL,
+        description: A2A_METHOD_DESCRIPTIONS[A2A_METHODS.TASKS_CANCEL],
+        paramsRequired: true,
+        streaming: false,
+        authRequired: false,
+    },
+    [A2A_METHODS.TASKS_RESUBMIT]: {
+        name: A2A_METHODS.TASKS_RESUBMIT,
+        description: A2A_METHOD_DESCRIPTIONS[A2A_METHODS.TASKS_RESUBMIT],
+        paramsRequired: true,
+        streaming: false,
+        authRequired: false,
+    },
+    [A2A_METHODS.TASKS_PUSH_NOTIFICATION_SET]: {
+        name: A2A_METHODS.TASKS_PUSH_NOTIFICATION_SET,
+        description: A2A_METHOD_DESCRIPTIONS[A2A_METHODS.TASKS_PUSH_NOTIFICATION_SET],
+        paramsRequired: true,
+        streaming: false,
+        authRequired: false,
+        requiredCapabilities: ['pushNotifications'],
+    },
+    [A2A_METHODS.TASKS_PUSH_NOTIFICATION_GET]: {
+        name: A2A_METHODS.TASKS_PUSH_NOTIFICATION_GET,
+        description: A2A_METHOD_DESCRIPTIONS[A2A_METHODS.TASKS_PUSH_NOTIFICATION_GET],
+        paramsRequired: true,
+        streaming: false,
+        authRequired: false,
+        requiredCapabilities: ['pushNotifications'],
+    },
+};
+// ============================================================================
+// Validation Utilities
+// ============================================================================
+/**
+ * Check if a string is a valid A2A method name.
+ */
+export function isValidMethod(method) {
+    return Object.values(A2A_METHODS).includes(method);
+}
+/**
+ * Get method metadata by name.
+ */
+export function getMethodMetadata(method) {
+    if (!isValidMethod(method)) {
+        return undefined;
+    }
+    return METHOD_METADATA[method];
+}
+/**
+ * Check if a method requires parameters.
+ */
+export function methodRequiresParams(method) {
+    const metadata = getMethodMetadata(method);
+    return metadata?.paramsRequired ?? true;
+}
+/**
+ * Check if a method supports streaming.
+ */
+export function isStreamingMethod(method) {
+    const metadata = getMethodMetadata(method);
+    return metadata?.streaming ?? false;
+}
+/**
+ * Get all available method names.
+ */
+export function getAllMethods() {
+    return Object.values(A2A_METHODS);
+}
+/**
+ * Get methods by category.
+ */
+export function getMethodsByCategory(category) {
+    switch (category) {
+        case 'messaging':
+            return [A2A_METHODS.MESSAGE_SEND, A2A_METHODS.MESSAGE_STREAM];
+        case 'tasks':
+            return [
+                A2A_METHODS.TASKS_GET,
+                A2A_METHODS.TASKS_LIST,
+                A2A_METHODS.TASKS_CANCEL,
+                A2A_METHODS.TASKS_RESUBMIT,
+            ];
+        case 'notifications':
+            return [A2A_METHODS.TASKS_PUSH_NOTIFICATION_SET, A2A_METHODS.TASKS_PUSH_NOTIFICATION_GET];
+    }
+}
+/**
+ * Check if a task status is terminal (cannot change).
+ */
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.includes(status);
+}
+/**
+ * Validate task status transition.
+ */
+export function isValidStatusTransition(from, to) {
+    // Terminal states cannot transition
+    if (isTerminalStatus(from)) {
+        return false;
+    }
+    // Valid transitions
+    const validTransitions = {
+        submitted: ['working', 'rejected', 'canceled'],
+        working: ['completed', 'failed', 'canceled', 'input_required', 'auth_required'],
+        input_required: ['working', 'canceled', 'failed'],
+        auth_required: ['working', 'canceled', 'failed'],
+        completed: [],
+        failed: [],
+        canceled: [],
+        rejected: [],
+    };
+    return validTransitions[from]?.includes(to) ?? false;
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard for TextPart.
+ */
+export function isTextPart(part) {
+    return part.type === 'text';
+}
+/**
+ * Type guard for FilePart.
+ */
+export function isFilePart(part) {
+    return part.type === 'file';
+}
+/**
+ * Type guard for DataPart.
+ */
+export function isDataPart(part) {
+    return part.type === 'data';
+}
+/**
+ * Extract text content from message parts.
+ */
+export function extractTextFromParts(parts) {
+    return parts
+        .filter(isTextPart)
+        .map((p) => p.text)
+        .join('\n');
+}
+/**
+ * Create a simple text message.
+ */
+export function createTextMessage(text, role = 'user') {
+    return {
+        role,
+        parts: [{ type: 'text', text }],
+    };
+}
+/**
+ * Create a data message.
+ */
+export function createDataMessage(data, role = 'user') {
+    return {
+        role,
+        parts: [{ type: 'data', data }],
+    };
+}
+//# sourceMappingURL=methods.js.map

package/v3/dist/adapters/a2a/jsonrpc/methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.js","sourceRoot":"","sources":["../../../../src/adapters/a2a/jsonrpc/methods.ts"],"names":[],"mappings":"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"}

package/v3/dist/adapters/a2a/notifications/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A2A Push Notifications Module
+ *
+ * Provides webhook-based push notifications for A2A task events.
+ * Implements the A2A protocol's pushNotifications capability.
+ *
+ * @module adapters/a2a/notifications
+ * @see https://a2a-protocol.org/latest/specification/
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createWebhookService,
+ *   generateSignatureHeader,
+ *   verifySignature,
+ * } from './notifications';
+ *
+ * // Create webhook service
+ * const webhookService = createWebhookService();
+ *
+ * // Subscribe to task notifications
+ * webhookService.subscribe('task-123', {
+ *   url: 'https://example.com/webhooks/a2a',
+ *   secret: 'webhook-secret',
+ *   events: ['task.completed', 'task.failed'],
+ *   timeout: 30000,
+ *   maxRetries: 5,
+ * });
+ *
+ * // Notify on state change
+ * await webhookService.notifyStateChange('task-123', 'completed', 'working');
+ *
+ * // Verify incoming webhook signature (on receiver side)
+ * const result = verifySignature(
+ *   requestBody,
+ *   request.headers['X-A2A-Signature'],
+ *   'webhook-secret'
+ * );
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+export { SIGNATURE_HEADER, SIGNATURE_VERSION, DEFAULT_MAX_AGE_MS, MIN_TIMESTAMP, type ParsedSignature, type VerificationResult, generateSignature, generateSignatureHeader, parseSignatureHeader, verifySignature, isValidSignature, } from './signature.js';
+export { type SubscriptionStatus, type Subscription, type CreateSubscriptionOptions, type UpdateSubscriptionOptions, type SubscriptionQueryOptions, type SubscriptionStats, type SubscriptionStoreConfig, DEFAULT_SUBSCRIPTION_STORE_CONFIG, SubscriptionStore, createSubscriptionStore, } from './subscription-store.js';
+export { type RetryConfig, type PendingDelivery, type DeliveryAttemptResult, type QueueStats, type RetryQueueConfig, DEFAULT_RETRY_CONFIG, DEFAULT_QUEUE_CONFIG, RetryQueue, createRetryQueue, } from './retry-queue.js';
+export { type WebhookEvent, type WebhookConfig, type WebhookPayload, type WebhookEventData, type DeliveryResult, type WebhookServiceConfig, type HttpClient, type HttpResponse, type WebhookMetrics, DEFAULT_WEBHOOK_CONFIG, DEFAULT_SERVICE_CONFIG, statusToEvent, WebhookService, createWebhookService, } from './webhook-service.js';
+/**
+ * All webhook event types
+ */
+export declare const WEBHOOK_EVENTS: readonly ["task.submitted", "task.working", "task.completed", "task.failed", "task.canceled", "task.input_required", "task.auth_required", "task.rejected", "task.artifact_created"];
+/**
+ * Task state change events
+ */
+export declare const STATE_CHANGE_EVENTS: readonly ["task.submitted", "task.working", "task.completed", "task.failed", "task.canceled", "task.input_required", "task.auth_required", "task.rejected"];
+/**
+ * Terminal state events (task is complete)
+ */
+export declare const TERMINAL_EVENTS: readonly ["task.completed", "task.failed", "task.canceled", "task.rejected"];
+//# sourceMappingURL=index.d.ts.map

package/v3/dist/adapters/a2a/notifications/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/a2a/notifications/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,iCAAiC,EACjC,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,EACV,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAM9B;;GAEG;AACH,eAAO,MAAM,cAAc,sLAUjB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,mBAAmB,6JAStB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,eAAe,8EAKlB,CAAC"}

package/v3/dist/adapters/a2a/notifications/index.js

@@ -0,0 +1,99 @@
+/**
+ * A2A Push Notifications Module
+ *
+ * Provides webhook-based push notifications for A2A task events.
+ * Implements the A2A protocol's pushNotifications capability.
+ *
+ * @module adapters/a2a/notifications
+ * @see https://a2a-protocol.org/latest/specification/
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createWebhookService,
+ *   generateSignatureHeader,
+ *   verifySignature,
+ * } from './notifications';
+ *
+ * // Create webhook service
+ * const webhookService = createWebhookService();
+ *
+ * // Subscribe to task notifications
+ * webhookService.subscribe('task-123', {
+ *   url: 'https://example.com/webhooks/a2a',
+ *   secret: 'webhook-secret',
+ *   events: ['task.completed', 'task.failed'],
+ *   timeout: 30000,
+ *   maxRetries: 5,
+ * });
+ *
+ * // Notify on state change
+ * await webhookService.notifyStateChange('task-123', 'completed', 'working');
+ *
+ * // Verify incoming webhook signature (on receiver side)
+ * const result = verifySignature(
+ *   requestBody,
+ *   request.headers['X-A2A-Signature'],
+ *   'webhook-secret'
+ * );
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+// ============================================================================
+// Signature Utilities
+// ============================================================================
+export { SIGNATURE_HEADER, SIGNATURE_VERSION, DEFAULT_MAX_AGE_MS, MIN_TIMESTAMP, generateSignature, generateSignatureHeader, parseSignatureHeader, verifySignature, isValidSignature, } from './signature.js';
+// ============================================================================
+// Subscription Store
+// ============================================================================
+export { DEFAULT_SUBSCRIPTION_STORE_CONFIG, SubscriptionStore, createSubscriptionStore, } from './subscription-store.js';
+// ============================================================================
+// Retry Queue
+// ============================================================================
+export { DEFAULT_RETRY_CONFIG, DEFAULT_QUEUE_CONFIG, RetryQueue, createRetryQueue, } from './retry-queue.js';
+// ============================================================================
+// Webhook Service
+// ============================================================================
+export { DEFAULT_WEBHOOK_CONFIG, DEFAULT_SERVICE_CONFIG, statusToEvent, WebhookService, createWebhookService, } from './webhook-service.js';
+// ============================================================================
+// Convenience Types
+// ============================================================================
+/**
+ * All webhook event types
+ */
+export const WEBHOOK_EVENTS = [
+    'task.submitted',
+    'task.working',
+    'task.completed',
+    'task.failed',
+    'task.canceled',
+    'task.input_required',
+    'task.auth_required',
+    'task.rejected',
+    'task.artifact_created',
+];
+/**
+ * Task state change events
+ */
+export const STATE_CHANGE_EVENTS = [
+    'task.submitted',
+    'task.working',
+    'task.completed',
+    'task.failed',
+    'task.canceled',
+    'task.input_required',
+    'task.auth_required',
+    'task.rejected',
+];
+/**
+ * Terminal state events (task is complete)
+ */
+export const TERMINAL_EVENTS = [
+    'task.completed',
+    'task.failed',
+    'task.canceled',
+    'task.rejected',
+];
+//# sourceMappingURL=index.js.map

package/v3/dist/adapters/a2a/notifications/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/adapters/a2a/notifications/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EAGb,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,OAAO,EAQL,iCAAiC,EACjC,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAEjC,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E,OAAO,EAML,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,EACV,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E,OAAO,EAUL,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,aAAa;IACb,eAAe;IACf,qBAAqB;IACrB,oBAAoB;IACpB,eAAe;IACf,uBAAuB;CACf,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,aAAa;IACb,eAAe;IACf,qBAAqB;IACrB,oBAAoB;IACpB,eAAe;CACP,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,gBAAgB;IAChB,aAAa;IACb,eAAe;IACf,eAAe;CACP,CAAC"}

package/v3/dist/adapters/a2a/notifications/retry-queue.d.ts

@@ -0,0 +1,225 @@
+/**
+ * A2A Webhook Retry Queue
+ *
+ * Implements exponential backoff retry logic for failed webhook deliveries.
+ * Supports configurable retry strategies and queue persistence.
+ *
+ * @module adapters/a2a/notifications/retry-queue
+ * @see https://a2a-protocol.org/latest/specification/
+ */
+import { EventEmitter } from 'events';
+/**
+ * Retry configuration options
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxAttempts: number;
+    /** Base delay between retries in milliseconds */
+    baseDelayMs: number;
+    /** Maximum delay between retries in milliseconds */
+    maxDelayMs: number;
+    /** Multiplier for exponential backoff */
+    backoffMultiplier: number;
+    /** Add random jitter to prevent thundering herd */
+    jitterEnabled?: boolean;
+    /** Maximum jitter as percentage of delay (0-1) */
+    jitterRatio?: number;
+}
+/**
+ * Pending delivery in the retry queue
+ */
+export interface PendingDelivery {
+    /** Unique delivery ID */
+    id: string;
+    /** Subscription ID for this delivery */
+    subscriptionId: string;
+    /** Task ID associated with this delivery */
+    taskId: string;
+    /** Webhook URL */
+    url: string;
+    /** Webhook secret for signing */
+    secret: string;
+    /** Payload to deliver */
+    payload: string;
+    /** Original timestamp when first attempted */
+    originalTimestamp: Date;
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Last error message */
+    lastError?: string;
+    /** Last HTTP status code */
+    lastStatusCode?: number;
+    /** Scheduled retry time */
+    scheduledAt: Date;
+    /** Retry configuration */
+    retryConfig: RetryConfig;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Delivery result from the retry processor
+ */
+export interface DeliveryAttemptResult {
+    /** Whether the delivery was successful */
+    success: boolean;
+    /** HTTP status code */
+    statusCode?: number;
+    /** Error message if failed */
+    error?: string;
+    /** Response time in milliseconds */
+    responseTimeMs?: number;
+    /** Whether to retry (false if max attempts reached or non-retryable error) */
+    shouldRetry: boolean;
+    /** Next attempt time if should retry */
+    nextAttemptAt?: Date;
+}
+/**
+ * Queue statistics
+ */
+export interface QueueStats {
+    /** Total items in queue */
+    totalItems: number;
+    /** Items by attempt count */
+    byAttempt: Record<number, number>;
+    /** Oldest item age in milliseconds */
+    oldestItemAgeMs: number;
+    /** Items ready to process (scheduled time passed) */
+    readyToProcess: number;
+    /** Items scheduled for future */
+    scheduledForLater: number;
+    /** Total processed items */
+    totalProcessed: number;
+    /** Total successful deliveries */
+    totalSuccess: number;
+    /** Total failed deliveries (gave up) */
+    totalFailed: number;
+}
+/**
+ * Queue configuration
+ */
+export interface RetryQueueConfig {
+    /** Maximum queue size */
+    maxQueueSize?: number;
+    /** Processing interval in milliseconds */
+    processingIntervalMs?: number;
+    /** Maximum concurrent deliveries */
+    maxConcurrent?: number;
+    /** Default retry configuration */
+    defaultRetryConfig?: Partial<RetryConfig>;
+    /** Enable automatic processing */
+    enableAutoProcessing?: boolean;
+}
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+export declare const DEFAULT_QUEUE_CONFIG: Required<RetryQueueConfig>;
+/**
+ * Retry queue for failed webhook deliveries
+ *
+ * Implements exponential backoff with jitter for reliable delivery.
+ */
+export declare class RetryQueue extends EventEmitter {
+    private readonly config;
+    private readonly queue;
+    private readonly scheduledIndex;
+    private processingTimer?;
+    private isProcessing;
+    private currentlyProcessing;
+    private stats;
+    private deliveryFn?;
+    constructor(config?: RetryQueueConfig);
+    /**
+     * Add a delivery to the retry queue
+     */
+    enqueue(delivery: PendingDelivery): void;
+    /**
+     * Create and enqueue a new delivery
+     */
+    enqueueNew(params: {
+        subscriptionId: string;
+        taskId: string;
+        url: string;
+        secret: string;
+        payload: string;
+        retryConfig?: Partial<RetryConfig>;
+        metadata?: Record<string, unknown>;
+    }): PendingDelivery;
+    /**
+     * Get a delivery by ID
+     */
+    get(id: string): PendingDelivery | undefined;
+    /**
+     * Check if a delivery is in the queue
+     */
+    has(id: string): boolean;
+    /**
+     * Remove a delivery from the queue
+     */
+    remove(id: string): boolean;
+    /**
+     * Remove all deliveries for a subscription
+     */
+    removeBySubscription(subscriptionId: string): number;
+    /**
+     * Remove all deliveries for a task
+     */
+    removeByTask(taskId: string): number;
+    /**
+     * Set the delivery function for processing
+     */
+    setDeliveryFunction(fn: (delivery: PendingDelivery) => Promise<DeliveryAttemptResult>): void;
+    /**
+     * Process the queue (call pending deliveries)
+     */
+    processQueue(): Promise<void>;
+    /**
+     * Process a single delivery
+     */
+    private processDelivery;
+    /**
+     * Reschedule a delivery for retry
+     */
+    private rescheduleDelivery;
+    /**
+     * Calculate the next retry time using exponential backoff
+     */
+    private calculateNextRetryTime;
+    /**
+     * Get deliveries ready to process
+     */
+    private getReadyDeliveries;
+    /**
+     * Start automatic processing
+     */
+    startProcessing(): void;
+    /**
+     * Stop automatic processing
+     */
+    stopProcessing(): void;
+    /**
+     * Get queue statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Get queue size
+     */
+    get size(): number;
+    /**
+     * Clear all failed retries (items that have reached max attempts)
+     */
+    clearFailed(): number;
+    /**
+     * Clear all items in the queue
+     */
+    clear(): void;
+    /**
+     * Destroy the queue
+     */
+    destroy(): void;
+    private addToScheduleIndex;
+    private removeFromScheduleIndex;
+    private evictOldest;
+}
+/**
+ * Create a new retry queue
+ */
+export declare function createRetryQueue(config?: RetryQueueConfig): RetryQueue;
+//# sourceMappingURL=retry-queue.d.ts.map

package/v3/dist/adapters/a2a/notifications/retry-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-queue.d.ts","sourceRoot":"","sources":["../../../../src/adapters/a2a/notifications/retry-queue.ts"],"names":[],"mappings":"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"}