agentic-qe 2.7.4 → 2.8.1

package/dist/edge/p2p/protocol/types.d.ts

@@ -0,0 +1,737 @@
+/**
+ * Agent-to-Agent Communication Protocol Types
+ *
+ * Type definitions for the protocol layer that enables secure agent-to-agent
+ * communication over WebRTC data channels. Includes message types, envelopes,
+ * routing information, and protocol errors.
+ *
+ * @module edge/p2p/protocol/types
+ * @version 1.0.0
+ */
+/**
+ * Current protocol version
+ */
+export declare const PROTOCOL_VERSION = "1.0.0";
+/**
+ * Minimum supported protocol version
+ */
+export declare const MIN_PROTOCOL_VERSION = "1.0.0";
+/**
+ * Maximum message size in bytes (64KB)
+ */
+export declare const MAX_MESSAGE_SIZE = 65536;
+/**
+ * Compression threshold in bytes (1KB)
+ */
+export declare const COMPRESSION_THRESHOLD = 1024;
+/**
+ * Default message TTL in milliseconds (30 seconds)
+ */
+export declare const DEFAULT_MESSAGE_TTL = 30000;
+/**
+ * Default heartbeat interval in milliseconds (15 seconds)
+ */
+export declare const DEFAULT_HEARTBEAT_INTERVAL = 15000;
+/**
+ * Default request timeout in milliseconds (10 seconds)
+ */
+export declare const DEFAULT_REQUEST_TIMEOUT = 10000;
+/**
+ * Maximum retry attempts for reliable delivery
+ */
+export declare const MAX_RETRY_ATTEMPTS = 3;
+/**
+ * Retry delay multiplier for exponential backoff
+ */
+export declare const RETRY_DELAY_MULTIPLIER = 2;
+/**
+ * Initial retry delay in milliseconds
+ */
+export declare const INITIAL_RETRY_DELAY = 1000;
+/**
+ * Message type enumeration
+ */
+export declare enum MessageType {
+    /** Request expecting a response */
+    REQUEST = "request",
+    /** Response to a request */
+    RESPONSE = "response",
+    /** Event notification (fire-and-forget) */
+    EVENT = "event",
+    /** Heartbeat/keepalive message */
+    HEARTBEAT = "heartbeat",
+    /** Error notification */
+    ERROR = "error",
+    /** Acknowledgment for reliable delivery */
+    ACK = "ack",
+    /** Negative acknowledgment */
+    NACK = "nack",
+    /** Handshake message */
+    HANDSHAKE = "handshake",
+    /** Handshake acknowledgment */
+    HANDSHAKE_ACK = "handshake_ack",
+    /** Protocol close message */
+    CLOSE = "close"
+}
+/**
+ * Message priority levels
+ */
+export declare enum MessagePriority {
+    /** Critical priority - immediate processing */
+    CRITICAL = 0,
+    /** High priority - processed before normal */
+    HIGH = 1,
+    /** Normal priority - standard processing */
+    NORMAL = 2,
+    /** Low priority - processed when idle */
+    LOW = 3
+}
+/**
+ * Delivery semantics for messages
+ */
+export declare enum DeliverySemantics {
+    /** At most once delivery (fire-and-forget) */
+    AT_MOST_ONCE = "at_most_once",
+    /** At least once delivery (may duplicate) */
+    AT_LEAST_ONCE = "at_least_once",
+    /** Exactly once delivery (requires deduplication) */
+    EXACTLY_ONCE = "exactly_once"
+}
+/**
+ * Routing mode for messages
+ */
+export declare enum RoutingMode {
+    /** Single recipient */
+    UNICAST = "unicast",
+    /** All recipients */
+    BROADCAST = "broadcast",
+    /** Selected group of recipients */
+    MULTICAST = "multicast",
+    /** Relay through intermediate nodes */
+    RELAY = "relay"
+}
+/**
+ * Protocol envelope header containing metadata
+ */
+export interface ProtocolHeader {
+    /** Protocol version */
+    version: string;
+    /** Unique message identifier */
+    messageId: string;
+    /** Correlation ID for request/response pairs */
+    correlationId?: string;
+    /** Message type */
+    type: MessageType;
+    /** Message priority */
+    priority: MessagePriority;
+    /** Sender agent ID */
+    senderId: string;
+    /** Recipient agent ID (or '*' for broadcast) */
+    recipientId: string;
+    /** Timestamp when message was created */
+    timestamp: number;
+    /** Time-to-live in milliseconds */
+    ttl: number;
+    /** Number of hops remaining (for relay) */
+    hopCount: number;
+    /** Maximum hops allowed */
+    maxHops: number;
+    /** Whether payload is compressed */
+    compressed: boolean;
+    /** Delivery semantics */
+    delivery: DeliverySemantics;
+    /** Routing mode */
+    routing: RoutingMode;
+    /** Schema version for payload */
+    schemaVersion: number;
+}
+/**
+ * Message metadata for tracking and analytics
+ */
+export interface MessageMetadata {
+    /** Original message size before compression */
+    originalSize?: number;
+    /** Compressed size */
+    compressedSize?: number;
+    /** Source channel name */
+    channel?: string;
+    /** Trace ID for distributed tracing */
+    traceId?: string;
+    /** Span ID for distributed tracing */
+    spanId?: string;
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Custom tags */
+    tags?: Record<string, string>;
+    /** Retry count */
+    retryCount?: number;
+    /** Time spent in queue (ms) */
+    queueTime?: number;
+}
+/**
+ * Routing information for message delivery
+ */
+export interface RoutingInfo {
+    /** Routing mode */
+    mode: RoutingMode;
+    /** Target peer IDs for multicast */
+    targets?: string[];
+    /** Room/group ID for multicast */
+    roomId?: string;
+    /** Path taken by message (for debugging) */
+    path?: string[];
+    /** Relay nodes used */
+    relayNodes?: string[];
+    /** Whether to exclude sender from broadcast */
+    excludeSender?: boolean;
+}
+/**
+ * Complete protocol envelope
+ */
+export interface ProtocolEnvelope<T = unknown> {
+    /** Protocol header */
+    header: ProtocolHeader;
+    /** Message payload */
+    payload: T;
+    /** Base64-encoded signature of header + payload */
+    signature: string;
+    /** Signer's public key (Base64) */
+    signerPublicKey: string;
+    /** Optional routing information */
+    routing?: RoutingInfo;
+    /** Optional metadata */
+    metadata?: MessageMetadata;
+}
+/**
+ * Request message payload
+ */
+export interface RequestPayload<T = unknown> {
+    /** Method/action to invoke */
+    method: string;
+    /** Request parameters */
+    params: T;
+    /** Expected response timeout (ms) */
+    timeout?: number;
+}
+/**
+ * Response message payload
+ */
+export interface ResponsePayload<T = unknown> {
+    /** Whether request succeeded */
+    success: boolean;
+    /** Response data (if success) */
+    result?: T;
+    /** Error information (if failure) */
+    error?: ProtocolErrorInfo;
+}
+/**
+ * Event message payload
+ */
+export interface EventPayload<T = unknown> {
+    /** Event name/type */
+    event: string;
+    /** Event data */
+    data: T;
+    /** Whether event requires acknowledgment */
+    requiresAck?: boolean;
+}
+/**
+ * Heartbeat message payload
+ */
+export interface HeartbeatPayload {
+    /** Sequence number for tracking */
+    sequence: number;
+    /** Sender's timestamp */
+    timestamp: number;
+    /** Whether this is a request or response */
+    isResponse: boolean;
+    /** Original timestamp (in response) */
+    originalTimestamp?: number;
+    /** Local stats snapshot */
+    stats?: HeartbeatStats;
+}
+/**
+ * Heartbeat statistics
+ */
+export interface HeartbeatStats {
+    /** Messages sent since last heartbeat */
+    messagesSent: number;
+    /** Messages received since last heartbeat */
+    messagesReceived: number;
+    /** Current message queue size */
+    queueSize: number;
+    /** Memory usage (bytes) */
+    memoryUsage?: number;
+}
+/**
+ * Handshake message payload
+ */
+export interface HandshakePayload {
+    /** Agent identity proof */
+    identityProof: {
+        agentId: string;
+        publicKey: string;
+        challenge: string;
+        signature: string;
+        timestamp: string;
+        expiresIn: number;
+    };
+    /** Supported protocol versions */
+    supportedVersions: string[];
+    /** Preferred protocol version */
+    preferredVersion: string;
+    /** Supported features */
+    features: ProtocolFeature[];
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Handshake acknowledgment payload
+ */
+export interface HandshakeAckPayload {
+    /** Agreed protocol version */
+    agreedVersion: string;
+    /** Agreed features */
+    agreedFeatures: ProtocolFeature[];
+    /** Session ID for this connection */
+    sessionId: string;
+    /** Server timestamp */
+    timestamp: number;
+    /** Server public key */
+    publicKey: string;
+}
+/**
+ * Close message payload
+ */
+export interface ClosePayload {
+    /** Close code */
+    code: CloseCode;
+    /** Human-readable reason */
+    reason: string;
+    /** Whether to attempt reconnection */
+    reconnect: boolean;
+}
+/**
+ * Acknowledgment payload
+ */
+export interface AckPayload {
+    /** Message ID being acknowledged */
+    messageId: string;
+    /** Acknowledgment timestamp */
+    timestamp: number;
+    /** Processing time (ms) */
+    processingTime?: number;
+}
+/**
+ * Negative acknowledgment payload
+ */
+export interface NackPayload {
+    /** Message ID being rejected */
+    messageId: string;
+    /** Rejection reason */
+    reason: string;
+    /** Error code */
+    code: ProtocolErrorCode;
+    /** Whether message should be retried */
+    retryable: boolean;
+    /** Suggested retry delay (ms) */
+    retryAfter?: number;
+}
+/**
+ * Protocol feature flags
+ */
+export declare enum ProtocolFeature {
+    /** Support for message compression */
+    COMPRESSION = "compression",
+    /** Support for message encryption (beyond transport) */
+    ENCRYPTION = "encryption",
+    /** Support for request/response pattern */
+    REQUEST_RESPONSE = "request_response",
+    /** Support for pub/sub pattern */
+    PUB_SUB = "pub_sub",
+    /** Support for message streaming */
+    STREAMING = "streaming",
+    /** Support for binary payloads */
+    BINARY = "binary",
+    /** Support for message batching */
+    BATCHING = "batching",
+    /** Support for message prioritization */
+    PRIORITIZATION = "prioritization",
+    /** Support for reliable delivery */
+    RELIABLE_DELIVERY = "reliable_delivery",
+    /** Support for exactly-once semantics */
+    EXACTLY_ONCE = "exactly_once",
+    /** Support for distributed tracing */
+    TRACING = "tracing",
+    /** Support for backpressure */
+    BACKPRESSURE = "backpressure"
+}
+/**
+ * Default supported features
+ */
+export declare const DEFAULT_FEATURES: ProtocolFeature[];
+/**
+ * Protocol error codes
+ */
+export declare enum ProtocolErrorCode {
+    UNKNOWN_ERROR = 1000,
+    INVALID_MESSAGE = 1001,
+    MESSAGE_TOO_LARGE = 1002,
+    UNSUPPORTED_VERSION = 1003,
+    UNSUPPORTED_FEATURE = 1004,
+    SERIALIZATION_ERROR = 1005,
+    DESERIALIZATION_ERROR = 1006,
+    COMPRESSION_ERROR = 1007,
+    DECOMPRESSION_ERROR = 1008,
+    AUTHENTICATION_FAILED = 2000,
+    INVALID_SIGNATURE = 2001,
+    EXPIRED_SIGNATURE = 2002,
+    UNKNOWN_SENDER = 2003,
+    UNAUTHORIZED = 2004,
+    IDENTITY_MISMATCH = 2005,
+    ROUTING_FAILED = 3000,
+    PEER_NOT_FOUND = 3001,
+    PEER_UNREACHABLE = 3002,
+    TTL_EXPIRED = 3003,
+    MAX_HOPS_EXCEEDED = 3004,
+    NO_ROUTE = 3005,
+    DELIVERY_FAILED = 4000,
+    TIMEOUT = 4001,
+    REJECTED = 4002,
+    DUPLICATE = 4003,
+    OUT_OF_ORDER = 4004,
+    QUEUE_FULL = 4005,
+    PROTOCOL_ERROR = 5000,
+    INVALID_STATE = 5001,
+    HANDSHAKE_FAILED = 5002,
+    CONNECTION_CLOSED = 5003,
+    RATE_LIMITED = 5004,
+    BACKPRESSURE = 5005,
+    RESOURCE_EXHAUSTED = 6000,
+    MEMORY_LIMIT = 6001,
+    QUEUE_LIMIT = 6002,
+    CONNECTION_LIMIT = 6003
+}
+/**
+ * Protocol error information
+ */
+export interface ProtocolErrorInfo {
+    /** Error code */
+    code: ProtocolErrorCode;
+    /** Human-readable message */
+    message: string;
+    /** Additional details */
+    details?: unknown;
+    /** Timestamp when error occurred */
+    timestamp: number;
+    /** Whether the operation can be retried */
+    retryable: boolean;
+    /** Suggested retry delay (ms) */
+    retryAfter?: number;
+}
+/**
+ * Close codes for protocol close messages
+ */
+export declare enum CloseCode {
+    /** Normal closure */
+    NORMAL = 1000,
+    /** Going away (e.g., server shutdown) */
+    GOING_AWAY = 1001,
+    /** Protocol error */
+    PROTOCOL_ERROR = 1002,
+    /** Unsupported data */
+    UNSUPPORTED_DATA = 1003,
+    /** No status received */
+    NO_STATUS = 1005,
+    /** Abnormal closure */
+    ABNORMAL = 1006,
+    /** Invalid payload */
+    INVALID_PAYLOAD = 1007,
+    /** Policy violation */
+    POLICY_VIOLATION = 1008,
+    /** Message too big */
+    MESSAGE_TOO_BIG = 1009,
+    /** Missing extension */
+    MISSING_EXTENSION = 1010,
+    /** Internal error */
+    INTERNAL_ERROR = 1011,
+    /** Service restart */
+    SERVICE_RESTART = 1012,
+    /** Try again later */
+    TRY_AGAIN_LATER = 1013
+}
+/**
+ * Protocol error class
+ */
+export declare class ProtocolError extends Error {
+    readonly code: ProtocolErrorCode;
+    readonly retryable: boolean;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: ProtocolErrorCode, retryable?: boolean, details?: unknown | undefined);
+    /**
+     * Convert to error info
+     */
+    toInfo(): ProtocolErrorInfo;
+    /**
+     * Create from error info
+     */
+    static fromInfo(info: ProtocolErrorInfo): ProtocolError;
+}
+/**
+ * Protocol state enumeration
+ */
+export declare enum ProtocolState {
+    /** Initial state, not connected */
+    IDLE = "idle",
+    /** Connecting, handshake in progress */
+    CONNECTING = "connecting",
+    /** Handshake complete, ready for messages */
+    ACTIVE = "active",
+    /** Closing gracefully */
+    CLOSING = "closing",
+    /** Closed permanently */
+    CLOSED = "closed",
+    /** Error state */
+    ERROR = "error"
+}
+/**
+ * Protocol state transition
+ */
+export interface ProtocolStateTransition {
+    /** Previous state */
+    from: ProtocolState;
+    /** New state */
+    to: ProtocolState;
+    /** Reason for transition */
+    reason: string;
+    /** Timestamp of transition */
+    timestamp: number;
+}
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+    /** Maximum messages per second */
+    messagesPerSecond: number;
+    /** Maximum bytes per second */
+    bytesPerSecond: number;
+    /** Maximum burst size (messages) */
+    burstSize: number;
+    /** Window size for rate limiting (ms) */
+    windowSize: number;
+    /** Whether to enable backpressure */
+    enableBackpressure: boolean;
+}
+/**
+ * Default rate limit configuration
+ */
+export declare const DEFAULT_RATE_LIMIT: RateLimitConfig;
+/**
+ * Rate limit status
+ */
+export interface RateLimitStatus {
+    /** Whether rate limited */
+    limited: boolean;
+    /** Current messages per second */
+    currentRate: number;
+    /** Remaining messages in window */
+    remaining: number;
+    /** Time until reset (ms) */
+    resetIn: number;
+    /** Suggested delay before retry (ms) */
+    retryAfter?: number;
+}
+/**
+ * Message queue configuration
+ */
+export interface QueueConfig {
+    /** Maximum queue size */
+    maxSize: number;
+    /** Maximum memory usage (bytes) */
+    maxMemory: number;
+    /** Enable priority queuing */
+    enablePriority: boolean;
+    /** Flush interval (ms) */
+    flushInterval: number;
+    /** Maximum batch size for processing */
+    batchSize: number;
+}
+/**
+ * Default queue configuration
+ */
+export declare const DEFAULT_QUEUE_CONFIG: QueueConfig;
+/**
+ * Queue statistics
+ */
+export interface QueueStats {
+    /** Current queue size */
+    size: number;
+    /** Current memory usage (bytes) */
+    memory: number;
+    /** Total messages enqueued */
+    totalEnqueued: number;
+    /** Total messages dequeued */
+    totalDequeued: number;
+    /** Total messages dropped */
+    totalDropped: number;
+    /** Average wait time (ms) */
+    averageWaitTime: number;
+    /** Messages by priority */
+    byPriority: Record<MessagePriority, number>;
+}
+/**
+ * Delivery status enumeration
+ */
+export declare enum DeliveryStatus {
+    /** Message pending delivery */
+    PENDING = "pending",
+    /** Message sent, awaiting acknowledgment */
+    SENT = "sent",
+    /** Message delivered (acknowledged) */
+    DELIVERED = "delivered",
+    /** Delivery failed */
+    FAILED = "failed",
+    /** Message expired (TTL) */
+    EXPIRED = "expired",
+    /** Delivery cancelled */
+    CANCELLED = "cancelled"
+}
+/**
+ * Delivery tracking information
+ */
+export interface DeliveryInfo {
+    /** Message ID */
+    messageId: string;
+    /** Current status */
+    status: DeliveryStatus;
+    /** Number of delivery attempts */
+    attempts: number;
+    /** Timestamp of first attempt */
+    firstAttemptAt: number;
+    /** Timestamp of last attempt */
+    lastAttemptAt: number;
+    /** Timestamp of delivery (if delivered) */
+    deliveredAt?: number;
+    /** Error info (if failed) */
+    error?: ProtocolErrorInfo;
+    /** Next retry timestamp */
+    nextRetryAt?: number;
+}
+/**
+ * Dead letter information
+ */
+export interface DeadLetter {
+    /** Original envelope */
+    envelope: ProtocolEnvelope;
+    /** Delivery info */
+    deliveryInfo: DeliveryInfo;
+    /** Timestamp when moved to dead letter */
+    deadLetteredAt: number;
+    /** Reason for dead lettering */
+    reason: string;
+}
+/**
+ * Agent channel configuration
+ */
+export interface ChannelConfig {
+    /** Local agent ID */
+    localAgentId: string;
+    /** Remote agent ID */
+    remoteAgentId: string;
+    /** Protocol version to use */
+    protocolVersion?: string;
+    /** Requested features */
+    features?: ProtocolFeature[];
+    /** Rate limit configuration */
+    rateLimit?: Partial<RateLimitConfig>;
+    /** Queue configuration */
+    queue?: Partial<QueueConfig>;
+    /** Request timeout (ms) */
+    requestTimeout?: number;
+    /** Heartbeat interval (ms) */
+    heartbeatInterval?: number;
+    /** Enable automatic reconnection */
+    autoReconnect?: boolean;
+    /** Maximum reconnection attempts */
+    maxReconnectAttempts?: number;
+}
+/**
+ * Channel statistics
+ */
+export interface ChannelStats {
+    /** Total messages sent */
+    messagesSent: number;
+    /** Total messages received */
+    messagesReceived: number;
+    /** Total bytes sent */
+    bytesSent: number;
+    /** Total bytes received */
+    bytesReceived: number;
+    /** Total requests sent */
+    requestsSent: number;
+    /** Total responses received */
+    responsesReceived: number;
+    /** Total events published */
+    eventsPublished: number;
+    /** Total events received */
+    eventsReceived: number;
+    /** Average request latency (ms) */
+    averageLatency: number;
+    /** Current connection state */
+    state: ProtocolState;
+    /** Last activity timestamp */
+    lastActivityAt: number;
+    /** Channel opened timestamp */
+    openedAt: number;
+    /** Reconnection count */
+    reconnectionCount: number;
+}
+/**
+ * Message handler function type
+ */
+export type MessageHandler<T = unknown, R = unknown> = (payload: T, envelope: ProtocolEnvelope<T>) => Promise<R> | R;
+/**
+ * Event handler function type
+ */
+export type EventHandler<T = unknown> = (data: T, envelope: ProtocolEnvelope<EventPayload<T>>) => void | Promise<void>;
+/**
+ * Error handler function type
+ */
+export type ErrorHandler = (error: ProtocolError, envelope?: ProtocolEnvelope) => void;
+/**
+ * State change handler function type
+ */
+export type StateChangeHandler = (transition: ProtocolStateTransition) => void;
+/**
+ * Generate unique message ID
+ */
+export declare function generateMessageId(): string;
+/**
+ * Generate session ID using cryptographically secure random values
+ */
+export declare function generateSessionId(): string;
+/**
+ * Generate trace ID
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate span ID
+ */
+export declare function generateSpanId(): string;
+/**
+ * Check if protocol version is supported
+ */
+export declare function isVersionSupported(version: string): boolean;
+/**
+ * Get error message for error code
+ */
+export declare function getErrorMessage(code: ProtocolErrorCode): string;
+/**
+ * Check if error is retryable
+ */
+export declare function isRetryableError(code: ProtocolErrorCode): boolean;
+/**
+ * Create default protocol header
+ */
+export declare function createDefaultHeader(type: MessageType, senderId: string, recipientId: string): ProtocolHeader;
+//# sourceMappingURL=types.d.ts.map