agentic-qe 2.7.4 → 2.8.0

package/dist/edge/p2p/protocol/ProtocolHandler.js

@@ -0,0 +1,930 @@
+"use strict";
+/**
+ * Protocol Handler for Agent-to-Agent Communication
+ *
+ * Manages protocol state machine, message signing/verification using Ed25519,
+ * heartbeat/keepalive management, protocol version negotiation, and rate limiting.
+ *
+ * @module edge/p2p/protocol/ProtocolHandler
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtocolHandler = exports.ProtocolEventType = void 0;
+exports.createProtocolHandler = createProtocolHandler;
+const crypto_1 = require("../crypto");
+const types_1 = require("./types");
+const MessageEncoder_1 = require("./MessageEncoder");
+/**
+ * Protocol handler event types
+ */
+var ProtocolEventType;
+(function (ProtocolEventType) {
+    ProtocolEventType["STATE_CHANGED"] = "state_changed";
+    ProtocolEventType["MESSAGE_SIGNED"] = "message_signed";
+    ProtocolEventType["MESSAGE_VERIFIED"] = "message_verified";
+    ProtocolEventType["VERIFICATION_FAILED"] = "verification_failed";
+    ProtocolEventType["HANDSHAKE_STARTED"] = "handshake_started";
+    ProtocolEventType["HANDSHAKE_COMPLETED"] = "handshake_completed";
+    ProtocolEventType["HANDSHAKE_FAILED"] = "handshake_failed";
+    ProtocolEventType["HEARTBEAT_SENT"] = "heartbeat_sent";
+    ProtocolEventType["HEARTBEAT_RECEIVED"] = "heartbeat_received";
+    ProtocolEventType["HEARTBEAT_TIMEOUT"] = "heartbeat_timeout";
+    ProtocolEventType["RATE_LIMITED"] = "rate_limited";
+    ProtocolEventType["CLOSING"] = "closing";
+    ProtocolEventType["CLOSED"] = "closed";
+})(ProtocolEventType || (exports.ProtocolEventType = ProtocolEventType = {}));
+// ============================================
+// ProtocolHandler Class
+// ============================================
+/**
+ * Protocol handler for agent-to-agent communication
+ *
+ * @example
+ * ```typescript
+ * const handler = new ProtocolHandler({
+ *   identity: myIdentity,
+ *   keyPair: myKeyPair,
+ * });
+ *
+ * // Start handshake
+ * const handshakeEnvelope = await handler.createHandshake();
+ *
+ * // Process incoming handshake
+ * const result = await handler.processHandshake(receivedEnvelope);
+ *
+ * // Create signed message
+ * const envelope = await handler.createMessage(MessageType.REQUEST, payload);
+ *
+ * // Verify incoming message
+ * const verified = await handler.verifyMessage(receivedEnvelope);
+ * ```
+ */
+class ProtocolHandler {
+    constructor(config) {
+        this.state = types_1.ProtocolState.IDLE;
+        this.eventHandlers = [];
+        // Session state
+        this.sessionId = null;
+        this.remoteIdentity = null;
+        this.agreedVersion = types_1.PROTOCOL_VERSION;
+        this.agreedFeatures = [];
+        // Heartbeat state
+        this.heartbeatSequence = 0;
+        this.lastHeartbeatSent = 0;
+        this.lastHeartbeatReceived = 0;
+        this.heartbeatTimer = null;
+        this.heartbeatTimeoutTimer = null;
+        // Message tracking
+        this.messageSequence = 0;
+        this.processedMessages = new Set();
+        this.messageTimestamps = new Map();
+        // Tracing
+        this.currentTraceId = null;
+        this.identity = config.identity;
+        this.keyPair = config.keyPair;
+        this.config = {
+            identity: config.identity,
+            keyPair: config.keyPair,
+            supportedVersions: config.supportedVersions ?? [types_1.PROTOCOL_VERSION],
+            features: config.features ?? types_1.DEFAULT_FEATURES,
+            heartbeatInterval: config.heartbeatInterval ?? types_1.DEFAULT_HEARTBEAT_INTERVAL,
+            heartbeatTimeout: config.heartbeatTimeout ?? types_1.DEFAULT_HEARTBEAT_INTERVAL * 2,
+            rateLimit: config.rateLimit ?? {},
+            enableTracing: config.enableTracing ?? false,
+            metadata: config.metadata ?? {},
+        };
+        this.rateLimitConfig = {
+            ...types_1.DEFAULT_RATE_LIMIT,
+            ...this.config.rateLimit,
+        };
+        this.rateLimitBucket = {
+            tokens: this.rateLimitConfig.burstSize,
+            lastRefill: Date.now(),
+            messageCount: 0,
+            byteCount: 0,
+        };
+        this.encoder = new MessageEncoder_1.MessageEncoder();
+        if (this.config.enableTracing) {
+            this.currentTraceId = (0, types_1.generateTraceId)();
+        }
+    }
+    // ============================================
+    // State Management
+    // ============================================
+    /**
+     * Get current protocol state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Transition to a new state
+     */
+    transitionTo(newState, reason) {
+        const oldState = this.state;
+        this.state = newState;
+        const transition = {
+            from: oldState,
+            to: newState,
+            reason,
+            timestamp: Date.now(),
+        };
+        this.emit({
+            type: ProtocolEventType.STATE_CHANGED,
+            timestamp: Date.now(),
+            details: transition,
+        });
+    }
+    /**
+     * Validate state transition
+     */
+    validateStateTransition(targetState) {
+        const validTransitions = {
+            [types_1.ProtocolState.IDLE]: [types_1.ProtocolState.CONNECTING, types_1.ProtocolState.CLOSED],
+            [types_1.ProtocolState.CONNECTING]: [
+                types_1.ProtocolState.ACTIVE,
+                types_1.ProtocolState.ERROR,
+                types_1.ProtocolState.CLOSED,
+            ],
+            [types_1.ProtocolState.ACTIVE]: [types_1.ProtocolState.CLOSING, types_1.ProtocolState.ERROR],
+            [types_1.ProtocolState.CLOSING]: [types_1.ProtocolState.CLOSED, types_1.ProtocolState.ERROR],
+            [types_1.ProtocolState.CLOSED]: [types_1.ProtocolState.IDLE],
+            [types_1.ProtocolState.ERROR]: [types_1.ProtocolState.IDLE, types_1.ProtocolState.CLOSED],
+        };
+        if (!validTransitions[this.state].includes(targetState)) {
+            throw new types_1.ProtocolError(`Invalid state transition from ${this.state} to ${targetState}`, types_1.ProtocolErrorCode.INVALID_STATE);
+        }
+    }
+    // ============================================
+    // Handshake
+    // ============================================
+    /**
+     * Create handshake message to initiate connection
+     */
+    async createHandshake() {
+        if (this.state !== types_1.ProtocolState.IDLE) {
+            throw new types_1.ProtocolError('Can only initiate handshake from IDLE state', types_1.ProtocolErrorCode.INVALID_STATE);
+        }
+        this.transitionTo(types_1.ProtocolState.CONNECTING, 'Initiating handshake');
+        // Generate challenge for identity proof
+        const challenge = crypto_1.Signer.generateChallenge();
+        // Create identity proof
+        const identityProof = await crypto_1.Signer.createIdentityProof(this.keyPair, this.identity, challenge);
+        const payload = {
+            identityProof: {
+                agentId: identityProof.agentId,
+                publicKey: identityProof.publicKey,
+                challenge: identityProof.challenge,
+                signature: identityProof.signature,
+                timestamp: identityProof.timestamp,
+                expiresIn: identityProof.expiresIn,
+            },
+            supportedVersions: this.config.supportedVersions,
+            preferredVersion: types_1.PROTOCOL_VERSION,
+            features: this.config.features,
+            metadata: this.config.metadata,
+        };
+        const envelope = await this.createMessage(types_1.MessageType.HANDSHAKE, payload, '*');
+        this.emit({
+            type: ProtocolEventType.HANDSHAKE_STARTED,
+            timestamp: Date.now(),
+        });
+        return envelope;
+    }
+    /**
+     * Process incoming handshake and create acknowledgment
+     */
+    async processHandshake(envelope) {
+        // Verify message signature
+        const verified = await this.verifyMessage(envelope);
+        if (!verified) {
+            this.transitionTo(types_1.ProtocolState.ERROR, 'Handshake signature verification failed');
+            return {
+                success: false,
+                error: new types_1.ProtocolError('Handshake signature verification failed', types_1.ProtocolErrorCode.INVALID_SIGNATURE),
+            };
+        }
+        const payload = envelope.payload;
+        // Verify identity proof
+        const proofResult = await crypto_1.Signer.verifyIdentityProof({
+            agentId: payload.identityProof.agentId,
+            publicKey: payload.identityProof.publicKey,
+            challenge: payload.identityProof.challenge,
+            signature: payload.identityProof.signature,
+            timestamp: payload.identityProof.timestamp,
+            expiresIn: payload.identityProof.expiresIn,
+        });
+        if (!proofResult.valid) {
+            this.transitionTo(types_1.ProtocolState.ERROR, 'Identity proof verification failed');
+            return {
+                success: false,
+                error: new types_1.ProtocolError(`Identity proof verification failed: ${proofResult.error}`, types_1.ProtocolErrorCode.AUTHENTICATION_FAILED),
+            };
+        }
+        // Negotiate version
+        const agreedVersion = this.negotiateVersion(payload.supportedVersions);
+        if (!agreedVersion) {
+            this.transitionTo(types_1.ProtocolState.ERROR, 'No common protocol version');
+            return {
+                success: false,
+                error: new types_1.ProtocolError('No common protocol version supported', types_1.ProtocolErrorCode.UNSUPPORTED_VERSION),
+            };
+        }
+        // Negotiate features
+        const agreedFeatures = this.negotiateFeatures(payload.features);
+        // Create session
+        this.sessionId = (0, types_1.generateSessionId)();
+        this.remoteIdentity = {
+            agentId: payload.identityProof.agentId,
+            publicKey: payload.identityProof.publicKey,
+            createdAt: new Date().toISOString(),
+            metadata: payload.metadata,
+        };
+        this.agreedVersion = agreedVersion;
+        this.agreedFeatures = agreedFeatures;
+        if (this.state === types_1.ProtocolState.IDLE) {
+            this.transitionTo(types_1.ProtocolState.CONNECTING, 'Received handshake');
+        }
+        this.emit({
+            type: ProtocolEventType.HANDSHAKE_COMPLETED,
+            timestamp: Date.now(),
+            details: {
+                remoteAgentId: this.remoteIdentity.agentId,
+                agreedVersion,
+                agreedFeatures,
+                sessionId: this.sessionId,
+            },
+        });
+        return {
+            success: true,
+            agreedVersion,
+            agreedFeatures,
+            sessionId: this.sessionId,
+            remoteIdentity: this.remoteIdentity,
+        };
+    }
+    /**
+     * Create handshake acknowledgment
+     */
+    async createHandshakeAck(result) {
+        if (!result.success) {
+            throw new types_1.ProtocolError('Cannot acknowledge failed handshake', types_1.ProtocolErrorCode.INVALID_STATE);
+        }
+        const payload = {
+            agreedVersion: result.agreedVersion,
+            agreedFeatures: result.agreedFeatures,
+            sessionId: result.sessionId,
+            timestamp: Date.now(),
+            publicKey: this.identity.publicKey,
+        };
+        const envelope = await this.createMessage(types_1.MessageType.HANDSHAKE_ACK, payload, result.remoteIdentity.agentId);
+        // Transition to active state
+        this.transitionTo(types_1.ProtocolState.ACTIVE, 'Handshake acknowledgment sent');
+        // Start heartbeat
+        this.startHeartbeat();
+        return envelope;
+    }
+    /**
+     * Process handshake acknowledgment
+     */
+    async processHandshakeAck(envelope) {
+        if (this.state !== types_1.ProtocolState.CONNECTING) {
+            throw new types_1.ProtocolError('Not expecting handshake acknowledgment', types_1.ProtocolErrorCode.INVALID_STATE);
+        }
+        // Verify signature
+        const verified = await this.verifyMessage(envelope);
+        if (!verified) {
+            this.transitionTo(types_1.ProtocolState.ERROR, 'Handshake ack signature verification failed');
+            return false;
+        }
+        const payload = envelope.payload;
+        // Store session info
+        this.sessionId = payload.sessionId;
+        this.agreedVersion = payload.agreedVersion;
+        this.agreedFeatures = payload.agreedFeatures;
+        this.remoteIdentity = {
+            agentId: envelope.header.senderId,
+            publicKey: payload.publicKey,
+            createdAt: new Date().toISOString(),
+        };
+        // Transition to active
+        this.transitionTo(types_1.ProtocolState.ACTIVE, 'Handshake acknowledgment received');
+        // Start heartbeat
+        this.startHeartbeat();
+        this.emit({
+            type: ProtocolEventType.HANDSHAKE_COMPLETED,
+            timestamp: Date.now(),
+            details: {
+                sessionId: this.sessionId,
+                agreedVersion: this.agreedVersion,
+                agreedFeatures: this.agreedFeatures,
+            },
+        });
+        return true;
+    }
+    /**
+     * Negotiate protocol version
+     */
+    negotiateVersion(remoteVersions) {
+        // Find highest common version
+        const commonVersions = this.config.supportedVersions.filter((v) => remoteVersions.includes(v));
+        if (commonVersions.length === 0) {
+            return null;
+        }
+        // Sort by version (semantic versioning)
+        commonVersions.sort((a, b) => {
+            const [aMajor, aMinor, aPatch] = a.split('.').map(Number);
+            const [bMajor, bMinor, bPatch] = b.split('.').map(Number);
+            return bMajor - aMajor || bMinor - aMinor || bPatch - aPatch;
+        });
+        return commonVersions[0];
+    }
+    /**
+     * Negotiate features
+     */
+    negotiateFeatures(remoteFeatures) {
+        return this.config.features.filter((f) => remoteFeatures.includes(f));
+    }
+    // ============================================
+    // Message Creation and Signing
+    // ============================================
+    /**
+     * Create a signed protocol envelope
+     */
+    async createMessage(type, payload, recipientId = '*', options = {}) {
+        // Check rate limit
+        const rateLimitStatus = this.checkRateLimit(1, 0);
+        if (rateLimitStatus.limited) {
+            this.emit({
+                type: ProtocolEventType.RATE_LIMITED,
+                timestamp: Date.now(),
+                details: rateLimitStatus,
+            });
+            throw new types_1.ProtocolError(`Rate limited. Retry after ${rateLimitStatus.retryAfter}ms`, types_1.ProtocolErrorCode.RATE_LIMITED, true);
+        }
+        // Create header
+        const header = {
+            version: this.agreedVersion,
+            messageId: (0, types_1.generateMessageId)(),
+            correlationId: options.correlationId,
+            type,
+            priority: options.priority ?? types_1.MessagePriority.NORMAL,
+            senderId: this.identity.agentId,
+            recipientId,
+            timestamp: Date.now(),
+            ttl: options.ttl ?? types_1.DEFAULT_MESSAGE_TTL,
+            hopCount: 0,
+            maxHops: 5,
+            compressed: false,
+            delivery: options.delivery ?? types_1.DeliverySemantics.AT_LEAST_ONCE,
+            routing: options.routing ?? types_1.RoutingMode.UNICAST,
+            schemaVersion: 1,
+        };
+        // Create metadata
+        const metadata = {};
+        if (this.config.enableTracing) {
+            metadata.traceId = this.currentTraceId ?? (0, types_1.generateTraceId)();
+            metadata.spanId = (0, types_1.generateSpanId)();
+        }
+        // Create message to sign
+        const messageToSign = {
+            header,
+            payload,
+        };
+        // Sign message
+        const signedMessage = await crypto_1.Signer.sign(this.keyPair, this.identity, messageToSign, true);
+        const envelope = {
+            header,
+            payload,
+            signature: signedMessage.signature,
+            signerPublicKey: signedMessage.signerPublicKey,
+            metadata,
+        };
+        // Consume rate limit token
+        this.consumeRateLimit(1, JSON.stringify(payload).length);
+        // Track message
+        this.messageSequence++;
+        this.messageTimestamps.set(header.messageId, Date.now());
+        this.emit({
+            type: ProtocolEventType.MESSAGE_SIGNED,
+            timestamp: Date.now(),
+            details: { messageId: header.messageId, type },
+        });
+        return envelope;
+    }
+    /**
+     * Verify a signed protocol envelope
+     */
+    async verifyMessage(envelope) {
+        try {
+            // Check for duplicates (replay protection)
+            if (this.processedMessages.has(envelope.header.messageId)) {
+                throw new types_1.ProtocolError('Duplicate message', types_1.ProtocolErrorCode.DUPLICATE);
+            }
+            // Check TTL
+            const age = Date.now() - envelope.header.timestamp;
+            if (age > envelope.header.ttl) {
+                throw new types_1.ProtocolError('Message expired', types_1.ProtocolErrorCode.TTL_EXPIRED);
+            }
+            // Check hop count
+            if (envelope.header.hopCount > envelope.header.maxHops) {
+                throw new types_1.ProtocolError('Max hops exceeded', types_1.ProtocolErrorCode.MAX_HOPS_EXCEEDED);
+            }
+            // Verify signature
+            const messageToVerify = {
+                header: envelope.header,
+                payload: envelope.payload,
+            };
+            // Create canonical JSON for verification
+            const canonical = crypto_1.Signer.canonicalizeJson(messageToVerify);
+            const encoder = new TextEncoder();
+            const messageBytes = encoder.encode(canonical);
+            // Recreate the signing context
+            const signingContext = {
+                payload: canonical,
+                publicKey: envelope.signerPublicKey,
+                signedAt: new Date(envelope.header.timestamp).toISOString(),
+                nonce: undefined, // The nonce was included in the original signing
+            };
+            const signedMessage = {
+                payload: messageToVerify,
+                signature: envelope.signature,
+                signerPublicKey: envelope.signerPublicKey,
+                signerId: envelope.header.senderId,
+                signedAt: new Date(envelope.header.timestamp).toISOString(),
+            };
+            const verifyResult = await crypto_1.Signer.verify(signedMessage);
+            if (!verifyResult.valid) {
+                this.emit({
+                    type: ProtocolEventType.VERIFICATION_FAILED,
+                    timestamp: Date.now(),
+                    details: {
+                        messageId: envelope.header.messageId,
+                        error: verifyResult.error,
+                    },
+                });
+                return false;
+            }
+            // Verify sender identity matches signature
+            if (verifyResult.signerId !== envelope.header.senderId) {
+                this.emit({
+                    type: ProtocolEventType.VERIFICATION_FAILED,
+                    timestamp: Date.now(),
+                    details: {
+                        messageId: envelope.header.messageId,
+                        error: 'Sender ID mismatch',
+                    },
+                });
+                return false;
+            }
+            // Mark message as processed
+            this.processedMessages.add(envelope.header.messageId);
+            // Cleanup old processed messages (keep last 10000)
+            if (this.processedMessages.size > 10000) {
+                const oldest = Array.from(this.processedMessages).slice(0, 5000);
+                for (const id of oldest) {
+                    this.processedMessages.delete(id);
+                }
+            }
+            this.emit({
+                type: ProtocolEventType.MESSAGE_VERIFIED,
+                timestamp: Date.now(),
+                details: { messageId: envelope.header.messageId },
+            });
+            return true;
+        }
+        catch (error) {
+            this.emit({
+                type: ProtocolEventType.VERIFICATION_FAILED,
+                timestamp: Date.now(),
+                details: {
+                    messageId: envelope.header.messageId,
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                },
+            });
+            return false;
+        }
+    }
+    // ============================================
+    // Heartbeat Management
+    // ============================================
+    /**
+     * Start heartbeat timer
+     */
+    startHeartbeat() {
+        if (this.heartbeatTimer)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            this.sendHeartbeat();
+        }, this.config.heartbeatInterval);
+        // Send initial heartbeat
+        this.sendHeartbeat();
+    }
+    /**
+     * Stop heartbeat timer
+     */
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.heartbeatTimeoutTimer) {
+            clearTimeout(this.heartbeatTimeoutTimer);
+            this.heartbeatTimeoutTimer = null;
+        }
+    }
+    /**
+     * Send heartbeat message
+     */
+    async sendHeartbeat() {
+        if (this.state !== types_1.ProtocolState.ACTIVE)
+            return null;
+        const payload = {
+            sequence: ++this.heartbeatSequence,
+            timestamp: Date.now(),
+            isResponse: false,
+            stats: {
+                messagesSent: this.messageSequence,
+                messagesReceived: this.processedMessages.size,
+                queueSize: 0, // Will be filled by router
+            },
+        };
+        try {
+            const envelope = await this.createMessage(types_1.MessageType.HEARTBEAT, payload, this.remoteIdentity?.agentId ?? '*', { priority: types_1.MessagePriority.HIGH });
+            this.lastHeartbeatSent = Date.now();
+            // Start timeout timer
+            this.startHeartbeatTimeout();
+            this.emit({
+                type: ProtocolEventType.HEARTBEAT_SENT,
+                timestamp: Date.now(),
+                details: { sequence: this.heartbeatSequence },
+            });
+            return envelope;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Process incoming heartbeat
+     */
+    async processHeartbeat(envelope) {
+        const payload = envelope.payload;
+        this.lastHeartbeatReceived = Date.now();
+        // Clear timeout timer
+        if (this.heartbeatTimeoutTimer) {
+            clearTimeout(this.heartbeatTimeoutTimer);
+            this.heartbeatTimeoutTimer = null;
+        }
+        this.emit({
+            type: ProtocolEventType.HEARTBEAT_RECEIVED,
+            timestamp: Date.now(),
+            details: {
+                sequence: payload.sequence,
+                latency: payload.isResponse ? Date.now() - payload.originalTimestamp : undefined,
+            },
+        });
+        // If this is a request, send response
+        if (!payload.isResponse) {
+            const responsePayload = {
+                sequence: payload.sequence,
+                timestamp: Date.now(),
+                isResponse: true,
+                originalTimestamp: payload.timestamp,
+                stats: {
+                    messagesSent: this.messageSequence,
+                    messagesReceived: this.processedMessages.size,
+                    queueSize: 0,
+                },
+            };
+            return this.createMessage(types_1.MessageType.HEARTBEAT, responsePayload, envelope.header.senderId, {
+                priority: types_1.MessagePriority.HIGH,
+            });
+        }
+        return null;
+    }
+    /**
+     * Start heartbeat timeout timer
+     */
+    startHeartbeatTimeout() {
+        if (this.heartbeatTimeoutTimer) {
+            clearTimeout(this.heartbeatTimeoutTimer);
+        }
+        this.heartbeatTimeoutTimer = setTimeout(() => {
+            this.handleHeartbeatTimeout();
+        }, this.config.heartbeatTimeout);
+    }
+    /**
+     * Handle heartbeat timeout
+     */
+    handleHeartbeatTimeout() {
+        this.emit({
+            type: ProtocolEventType.HEARTBEAT_TIMEOUT,
+            timestamp: Date.now(),
+            details: {
+                lastSent: this.lastHeartbeatSent,
+                lastReceived: this.lastHeartbeatReceived,
+            },
+        });
+        // Transition to error state after timeout
+        this.transitionTo(types_1.ProtocolState.ERROR, 'Heartbeat timeout');
+    }
+    /**
+     * Get heartbeat latency (ms)
+     */
+    getHeartbeatLatency() {
+        if (this.lastHeartbeatSent === 0 || this.lastHeartbeatReceived === 0) {
+            return null;
+        }
+        return this.lastHeartbeatReceived - this.lastHeartbeatSent;
+    }
+    // ============================================
+    // Rate Limiting
+    // ============================================
+    /**
+     * Check rate limit without consuming
+     */
+    checkRateLimit(messages, bytes) {
+        this.refillBucket();
+        const limited = this.rateLimitBucket.tokens < messages ||
+            this.rateLimitBucket.byteCount + bytes > this.rateLimitConfig.bytesPerSecond;
+        const remaining = Math.floor(this.rateLimitBucket.tokens);
+        const resetIn = this.rateLimitConfig.windowSize - (Date.now() - this.rateLimitBucket.lastRefill);
+        return {
+            limited,
+            currentRate: this.rateLimitBucket.messageCount,
+            remaining,
+            resetIn: Math.max(0, resetIn),
+            retryAfter: limited ? resetIn : undefined,
+        };
+    }
+    /**
+     * Consume rate limit tokens
+     */
+    consumeRateLimit(messages, bytes) {
+        this.rateLimitBucket.tokens -= messages;
+        this.rateLimitBucket.messageCount += messages;
+        this.rateLimitBucket.byteCount += bytes;
+    }
+    /**
+     * Refill rate limit bucket based on elapsed time
+     */
+    refillBucket() {
+        const now = Date.now();
+        const elapsed = now - this.rateLimitBucket.lastRefill;
+        if (elapsed >= this.rateLimitConfig.windowSize) {
+            // Full reset
+            this.rateLimitBucket.tokens = this.rateLimitConfig.burstSize;
+            this.rateLimitBucket.messageCount = 0;
+            this.rateLimitBucket.byteCount = 0;
+            this.rateLimitBucket.lastRefill = now;
+        }
+        else {
+            // Partial refill
+            const refillRate = this.rateLimitConfig.messagesPerSecond / (1000 / this.rateLimitConfig.windowSize);
+            const refillAmount = (elapsed / this.rateLimitConfig.windowSize) * refillRate;
+            this.rateLimitBucket.tokens = Math.min(this.rateLimitConfig.burstSize, this.rateLimitBucket.tokens + refillAmount);
+        }
+    }
+    /**
+     * Get current rate limit status
+     */
+    getRateLimitStatus() {
+        return this.checkRateLimit(0, 0);
+    }
+    // ============================================
+    // Message Creation Helpers
+    // ============================================
+    /**
+     * Create request message
+     */
+    async createRequest(method, params, recipientId, timeout) {
+        const payload = {
+            method,
+            params,
+            timeout,
+        };
+        return this.createMessage(types_1.MessageType.REQUEST, payload, recipientId);
+    }
+    /**
+     * Create response message
+     */
+    async createResponse(correlationId, result, recipientId) {
+        const payload = {
+            success: true,
+            result,
+        };
+        return this.createMessage(types_1.MessageType.RESPONSE, payload, recipientId, { correlationId });
+    }
+    /**
+     * Create error response
+     */
+    async createErrorResponse(correlationId, error, recipientId) {
+        const payload = {
+            success: false,
+            error: error.toInfo(),
+        };
+        return this.createMessage(types_1.MessageType.RESPONSE, payload, recipientId, { correlationId });
+    }
+    /**
+     * Create event message
+     */
+    async createEvent(event, data, recipientId = '*', requiresAck = false) {
+        const payload = {
+            event,
+            data,
+            requiresAck,
+        };
+        return this.createMessage(types_1.MessageType.EVENT, payload, recipientId, {
+            routing: recipientId === '*' ? types_1.RoutingMode.BROADCAST : types_1.RoutingMode.UNICAST,
+        });
+    }
+    /**
+     * Create acknowledgment message
+     */
+    async createAck(messageId, recipientId) {
+        const payload = {
+            messageId,
+            timestamp: Date.now(),
+        };
+        return this.createMessage(types_1.MessageType.ACK, payload, recipientId, {
+            priority: types_1.MessagePriority.HIGH,
+        });
+    }
+    /**
+     * Create negative acknowledgment message
+     */
+    async createNack(messageId, reason, code, recipientId) {
+        const payload = {
+            messageId,
+            reason,
+            code,
+            retryable: (0, types_1.isRetryableError)(code),
+        };
+        return this.createMessage(types_1.MessageType.NACK, payload, recipientId, {
+            priority: types_1.MessagePriority.HIGH,
+        });
+    }
+    // ============================================
+    // Connection Close
+    // ============================================
+    /**
+     * Create close message
+     */
+    async createClose(code = types_1.CloseCode.NORMAL, reason = 'Connection closed', reconnect = false) {
+        this.validateStateTransition(types_1.ProtocolState.CLOSING);
+        this.transitionTo(types_1.ProtocolState.CLOSING, reason);
+        this.emit({
+            type: ProtocolEventType.CLOSING,
+            timestamp: Date.now(),
+            details: { code, reason, reconnect },
+        });
+        const payload = {
+            code,
+            reason,
+            reconnect,
+        };
+        return this.createMessage(types_1.MessageType.CLOSE, payload, this.remoteIdentity?.agentId ?? '*', { priority: types_1.MessagePriority.CRITICAL });
+    }
+    /**
+     * Process close message
+     */
+    processClose(envelope) {
+        const payload = envelope.payload;
+        this.transitionTo(types_1.ProtocolState.CLOSED, payload.reason);
+        this.stopHeartbeat();
+        this.emit({
+            type: ProtocolEventType.CLOSED,
+            timestamp: Date.now(),
+            details: payload,
+        });
+        return payload;
+    }
+    /**
+     * Close connection
+     */
+    close() {
+        this.stopHeartbeat();
+        if (this.state !== types_1.ProtocolState.CLOSED) {
+            this.transitionTo(types_1.ProtocolState.CLOSED, 'Local close');
+        }
+        this.emit({
+            type: ProtocolEventType.CLOSED,
+            timestamp: Date.now(),
+        });
+    }
+    // ============================================
+    // Events
+    // ============================================
+    /**
+     * Add event handler
+     */
+    on(handler) {
+        this.eventHandlers.push(handler);
+    }
+    /**
+     * Remove event handler
+     */
+    off(handler) {
+        const index = this.eventHandlers.indexOf(handler);
+        if (index !== -1) {
+            this.eventHandlers.splice(index, 1);
+        }
+    }
+    /**
+     * Emit event to handlers
+     */
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+    // ============================================
+    // Getters
+    // ============================================
+    /**
+     * Get session ID
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Get remote identity
+     */
+    getRemoteIdentity() {
+        return this.remoteIdentity;
+    }
+    /**
+     * Get agreed protocol version
+     */
+    getAgreedVersion() {
+        return this.agreedVersion;
+    }
+    /**
+     * Get agreed features
+     */
+    getAgreedFeatures() {
+        return [...this.agreedFeatures];
+    }
+    /**
+     * Check if a feature is enabled
+     */
+    hasFeature(feature) {
+        return this.agreedFeatures.includes(feature);
+    }
+    /**
+     * Get local identity
+     */
+    getLocalIdentity() {
+        return this.identity;
+    }
+    /**
+     * Get message encoder
+     */
+    getEncoder() {
+        return this.encoder;
+    }
+    // ============================================
+    // Reset
+    // ============================================
+    /**
+     * Reset handler state
+     */
+    reset() {
+        this.stopHeartbeat();
+        this.state = types_1.ProtocolState.IDLE;
+        this.sessionId = null;
+        this.remoteIdentity = null;
+        this.agreedVersion = types_1.PROTOCOL_VERSION;
+        this.agreedFeatures = [];
+        this.heartbeatSequence = 0;
+        this.lastHeartbeatSent = 0;
+        this.lastHeartbeatReceived = 0;
+        this.messageSequence = 0;
+        this.processedMessages.clear();
+        this.messageTimestamps.clear();
+        // Reset rate limit bucket
+        this.rateLimitBucket = {
+            tokens: this.rateLimitConfig.burstSize,
+            lastRefill: Date.now(),
+            messageCount: 0,
+            byteCount: 0,
+        };
+    }
+}
+exports.ProtocolHandler = ProtocolHandler;
+// ============================================
+// Factory Functions
+// ============================================
+/**
+ * Create a new protocol handler
+ */
+function createProtocolHandler(config) {
+    return new ProtocolHandler(config);
+}
+//# sourceMappingURL=ProtocolHandler.js.map