digital-workers 2.1.1 → 2.3.0

package/dist/agent-comms.js

@@ -0,0 +1,677 @@
+/**
+ * Agent-to-Agent Communication Layer
+ *
+ * Provides structured messaging, coordination patterns, and handoff protocols
+ * for communication between agents in the digital-workers system.
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// AgentMessageBus Implementation
+// =============================================================================
+/**
+ * Agent message bus for routing messages between agents
+ */
+export class AgentMessageBus {
+    subscriptions = new Map();
+    pendingAcks = new Map();
+    messageStatus = new Map();
+    handoffs = new Map();
+    storedMessages = [];
+    messageQueue = new Map();
+    processingAgent = new Set();
+    disposed = false;
+    options;
+    constructor(options = {}) {
+        this.options = {
+            persistence: options.persistence ?? false,
+            defaultTtl: options.defaultTtl ?? 30000,
+            maxQueueSize: options.maxQueueSize ?? 1000,
+        };
+    }
+    /**
+     * Send a message to an agent
+     */
+    async send(message) {
+        if (this.disposed) {
+            return this.createFailedEnvelope(message, 'Message bus disposed');
+        }
+        const envelope = {
+            message,
+            deliveryAttempts: 1,
+            firstAttemptAt: new Date(),
+            lastAttemptAt: new Date(),
+            status: 'pending',
+        };
+        // Store message if persistence is enabled
+        if (this.options.persistence) {
+            this.storedMessages.push({ envelope: envelope, storedAt: new Date() });
+        }
+        // Get subscriptions for recipient
+        const subs = this.subscriptions.get(message.recipient);
+        if (!subs || subs.length === 0) {
+            envelope.status = 'failed';
+            envelope.error = `Agent '${message.recipient}' not found`;
+            this.messageStatus.set(message.id, 'failed');
+            return envelope;
+        }
+        // Track pending acknowledgment
+        if (message.type === 'request') {
+            const senderAcks = this.pendingAcks.get(message.sender) ?? new Set();
+            senderAcks.add(message.id);
+            this.pendingAcks.set(message.sender, senderAcks);
+        }
+        // Setup TTL expiration
+        if (message.ttl) {
+            setTimeout(() => {
+                if (this.messageStatus.get(message.id) !== 'acknowledged') {
+                    this.messageStatus.set(message.id, 'expired');
+                }
+            }, message.ttl);
+        }
+        // Deliver to matching subscribers
+        try {
+            await this.deliverMessage(message, subs);
+            envelope.status = 'delivered';
+            this.messageStatus.set(message.id, 'delivered');
+        }
+        catch (error) {
+            envelope.status = 'failed';
+            envelope.error = error instanceof Error ? error.message : String(error);
+            this.messageStatus.set(message.id, 'failed');
+        }
+        return envelope;
+    }
+    /**
+     * Deliver message to subscribers with queue handling
+     */
+    async deliverMessage(message, subs) {
+        const matchingSubs = subs.filter((sub) => this.matchesFilter(message, sub.options));
+        if (matchingSubs.length === 0) {
+            return;
+        }
+        // Queue messages if agent is busy
+        if (this.processingAgent.has(message.recipient)) {
+            const queue = this.messageQueue.get(message.recipient) ?? [];
+            queue.push(message);
+            this.messageQueue.set(message.recipient, queue);
+            return;
+        }
+        this.processingAgent.add(message.recipient);
+        try {
+            await Promise.all(matchingSubs.map((sub) => sub.handler(message)));
+        }
+        finally {
+            this.processingAgent.delete(message.recipient);
+            await this.processQueue(message.recipient, subs);
+        }
+    }
+    /**
+     * Process queued messages
+     */
+    async processQueue(agentId, subs) {
+        const queue = this.messageQueue.get(agentId);
+        if (!queue || queue.length === 0)
+            return;
+        const nextMessage = queue.shift();
+        this.messageQueue.set(agentId, queue);
+        await this.deliverMessage(nextMessage, subs);
+    }
+    /**
+     * Check if message matches subscription filter
+     */
+    matchesFilter(message, options) {
+        if (!options)
+            return true;
+        if (options.types && !options.types.includes(message.type))
+            return false;
+        if (options.from && message.sender !== options.from)
+            return false;
+        return true;
+    }
+    /**
+     * Subscribe to messages for an agent
+     */
+    subscribe(agentId, handler, options) {
+        const subs = this.subscriptions.get(agentId) ?? [];
+        const subscription = { handler, ...(options !== undefined && { options }) };
+        subs.push(subscription);
+        this.subscriptions.set(agentId, subs);
+        return () => {
+            const currentSubs = this.subscriptions.get(agentId) ?? [];
+            const index = currentSubs.indexOf(subscription);
+            if (index !== -1) {
+                currentSubs.splice(index, 1);
+                this.subscriptions.set(agentId, currentSubs);
+            }
+        };
+    }
+    /**
+     * Acknowledge a message
+     */
+    async acknowledge(messageId, agentId, status) {
+        this.messageStatus.set(messageId, 'acknowledged');
+        // Remove from pending acks
+        for (const entry of Array.from(this.pendingAcks.entries())) {
+            const [sender, acks] = entry;
+            if (acks.has(messageId)) {
+                acks.delete(messageId);
+                this.pendingAcks.set(sender, acks);
+                break;
+            }
+        }
+    }
+    /**
+     * Get pending acknowledgments for a sender
+     */
+    getPendingAcks(senderId) {
+        const acks = this.pendingAcks.get(senderId);
+        return acks ? Array.from(acks) : [];
+    }
+    /**
+     * Get message delivery status
+     */
+    getMessageStatus(messageId) {
+        return this.messageStatus.get(messageId);
+    }
+    /**
+     * Get handoff status
+     */
+    getHandoffStatus(handoffId) {
+        return this.handoffs.get(handoffId)?.status;
+    }
+    /**
+     * Get handoff history (previous attempts)
+     */
+    getHandoffHistory(handoffId) {
+        return this.handoffs.get(handoffId)?.previousAttempts ?? [];
+    }
+    /**
+     * Register a handoff
+     */
+    registerHandoff(request, originalMessage) {
+        const state = {
+            request,
+            status: 'pending',
+            previousAttempts: request.previousAttempt ? [request.previousAttempt] : [],
+            ...(originalMessage !== undefined && { originalMessage }),
+        };
+        // Setup timeout if specified
+        if (request.timeout) {
+            state.timeoutId = setTimeout(() => {
+                const currentState = this.handoffs.get(request.id);
+                if (currentState && currentState.status === 'pending') {
+                    currentState.status = 'expired';
+                    this.handoffs.set(request.id, currentState);
+                    // Notify initiator of timeout
+                    if (request.onTimeout) {
+                        const timeoutMsg = {
+                            id: `timeout_${request.id}`,
+                            type: 'handoff',
+                            sender: 'system',
+                            recipient: request.fromAgent,
+                            payload: { action: 'timeout', handoffId: request.id },
+                            timestamp: new Date(),
+                        };
+                        request.onTimeout(timeoutMsg);
+                    }
+                }
+            }, request.timeout);
+        }
+        this.handoffs.set(request.id, state);
+    }
+    /**
+     * Get handoff request info
+     */
+    getHandoffRequest(handoffId) {
+        return this.handoffs.get(handoffId)?.request;
+    }
+    /**
+     * Update handoff status
+     */
+    updateHandoffStatus(handoffId, status) {
+        const state = this.handoffs.get(handoffId);
+        if (state) {
+            // Clear timeout if pending timeout exists
+            if (state.timeoutId) {
+                clearTimeout(state.timeoutId);
+            }
+            state.status = status;
+            this.handoffs.set(handoffId, state);
+        }
+    }
+    /**
+     * Get stored messages (for persistence)
+     */
+    getStoredMessages() {
+        return this.storedMessages.map((s) => s.envelope);
+    }
+    /**
+     * Get message history for an agent
+     */
+    getMessageHistory(agentId, options) {
+        let messages = this.storedMessages
+            .filter((s) => s.envelope.message.recipient === agentId || s.envelope.message.sender === agentId)
+            .map((s) => s.envelope);
+        if (options?.from) {
+            messages = messages.filter((m) => m.message.timestamp >= options.from);
+        }
+        if (options?.to) {
+            messages = messages.filter((m) => m.message.timestamp <= options.to);
+        }
+        if (options?.limit) {
+            messages = messages.slice(-options.limit);
+        }
+        return messages;
+    }
+    /**
+     * Clear old messages
+     */
+    clearMessages(options) {
+        if (options?.olderThan) {
+            this.storedMessages = this.storedMessages.filter((s) => s.storedAt >= options.olderThan);
+        }
+        else {
+            this.storedMessages = [];
+        }
+    }
+    /**
+     * Dispose the message bus
+     */
+    dispose() {
+        this.disposed = true;
+        this.subscriptions.clear();
+        this.pendingAcks.clear();
+        this.messageStatus.clear();
+        this.messageQueue.clear();
+        this.processingAgent.clear();
+        // Clear all handoff timeouts
+        for (const state of Array.from(this.handoffs.values())) {
+            if (state.timeoutId) {
+                clearTimeout(state.timeoutId);
+            }
+        }
+        this.handoffs.clear();
+    }
+    /**
+     * Create a failed envelope
+     */
+    createFailedEnvelope(message, error) {
+        return {
+            message,
+            deliveryAttempts: 0,
+            firstAttemptAt: new Date(),
+            lastAttemptAt: new Date(),
+            status: 'failed',
+            error,
+        };
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a new message bus instance
+ */
+export function createMessageBus(options) {
+    return new AgentMessageBus(options);
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Generate a unique message ID
+ */
+function generateMessageId() {
+    return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+/**
+ * Generate a unique handoff ID
+ */
+function generateHandoffId() {
+    return `handoff_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+/**
+ * Generate a unique correlation ID
+ */
+function generateCorrelationId() {
+    return `corr_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+/**
+ * Resolve agent ID from Worker, WorkerRef, or string
+ */
+function resolveAgentId(agent) {
+    if (typeof agent === 'string')
+        return agent;
+    return agent.id;
+}
+/**
+ * Send a message to a specific agent
+ */
+export async function sendToAgent(bus, sender, recipient, payload, options) {
+    const message = {
+        id: generateMessageId(),
+        type: 'notification',
+        sender: resolveAgentId(sender),
+        recipient: resolveAgentId(recipient),
+        payload,
+        timestamp: new Date(),
+        ...(options?.priority !== undefined && { priority: options.priority }),
+        ...(options?.ttl !== undefined && { ttl: options.ttl }),
+        ...(options?.correlationId !== undefined && { correlationId: options.correlationId }),
+        ...(options?.metadata !== undefined && { metadata: options.metadata }),
+    };
+    return bus.send(message);
+}
+/**
+ * Broadcast a message to multiple agents
+ */
+export async function broadcastToGroup(bus, sender, recipients, payload, options) {
+    const correlationId = options?.correlationId ?? generateCorrelationId();
+    const results = await Promise.all(recipients.map((recipient) => sendToAgent(bus, sender, recipient, payload, {
+        ...options,
+        correlationId,
+    })));
+    return results;
+}
+/**
+ * Send a request to an agent and await response
+ */
+export async function requestFromAgent(bus, sender, recipient, payload, options) {
+    const senderId = resolveAgentId(sender);
+    const recipientId = resolveAgentId(recipient);
+    const messageId = generateMessageId();
+    const timeout = options?.timeout ?? 30000;
+    return new Promise((resolve, reject) => {
+        let timeoutId;
+        let unsubscribe;
+        // Setup response handler
+        unsubscribe = bus.subscribe(senderId, (response) => {
+            if (response.correlationId === messageId) {
+                clearTimeout(timeoutId);
+                unsubscribe?.();
+                if (response.type === 'error') {
+                    const errorPayload = response.payload;
+                    reject(new Error(errorPayload.error ?? 'Request failed'));
+                }
+                else {
+                    resolve(response);
+                }
+            }
+        });
+        // Setup timeout
+        timeoutId = setTimeout(() => {
+            unsubscribe?.();
+            reject(new Error('Request timeout'));
+        }, timeout);
+        // Send request
+        const message = {
+            id: messageId,
+            type: 'request',
+            sender: senderId,
+            recipient: recipientId,
+            payload,
+            timestamp: new Date(),
+            correlationId: messageId,
+            replyTo: senderId,
+            ...(options?.priority !== undefined && { priority: options.priority }),
+            ...(options?.ttl !== undefined && { ttl: options.ttl }),
+            ...(options?.metadata !== undefined && { metadata: options.metadata }),
+        };
+        bus
+            .send(message)
+            .then((envelope) => {
+            // Fail fast if delivery failed (recipient not found, etc.)
+            if (envelope.status === 'failed') {
+                clearTimeout(timeoutId);
+                unsubscribe?.();
+                reject(new Error(envelope.error ?? 'Message delivery failed'));
+            }
+        })
+            .catch((error) => {
+            clearTimeout(timeoutId);
+            unsubscribe?.();
+            reject(error);
+        });
+    });
+}
+/**
+ * Register a message handler for an agent
+ */
+export function onMessage(bus, agentId, handler, options) {
+    return bus.subscribe(agentId, handler, {
+        ...(options?.from !== undefined && { from: options.from }),
+        ...(options?.types !== undefined && { types: options.types }),
+    });
+}
+/**
+ * Send an acknowledgment for a received message
+ */
+export async function acknowledge(bus, message, status, result) {
+    // Send ack message to original sender
+    const ackMessage = {
+        id: generateMessageId(),
+        type: 'ack',
+        sender: message.recipient,
+        recipient: message.sender,
+        payload: {
+            messageId: message.id,
+            status,
+            timestamp: new Date(),
+            agentId: message.recipient,
+            result,
+        },
+        timestamp: new Date(),
+        correlationId: message.id,
+    };
+    await bus.send(ackMessage);
+    await bus.acknowledge(message.id, message.recipient, status);
+}
+/**
+ * Execute request-response pattern
+ */
+export async function requestResponse(bus, options) {
+    return requestFromAgent(bus, options.from, options.to, options.payload, {
+        ...(options.timeout !== undefined && { timeout: options.timeout }),
+        ...(options.priority !== undefined && { priority: options.priority }),
+    });
+}
+/**
+ * Execute fan-out pattern - distribute work to multiple agents
+ */
+export async function fanOut(bus, options) {
+    const correlationId = generateCorrelationId();
+    const timeout = options.timeout ?? 30000;
+    const fromId = resolveAgentId(options.from);
+    const results = await Promise.all(options.to.map(async (agent) => {
+        const agentId = resolveAgentId(agent);
+        try {
+            const response = await requestFromAgent(bus, fromId, agentId, options.payload, {
+                timeout,
+                correlationId,
+            });
+            return {
+                agentId,
+                success: true,
+                payload: response.payload,
+            };
+        }
+        catch (error) {
+            if (!options.continueOnError) {
+                throw error;
+            }
+            return {
+                agentId,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }));
+    return results;
+}
+/**
+ * Execute fan-in pattern - collect responses from multiple agents
+ */
+export async function fanIn(bus, options) {
+    const results = await Promise.all(options.sources.map((source) => {
+        const sourceId = resolveAgentId(source);
+        return options.onSourceMessage(sourceId);
+    }));
+    return results;
+}
+/**
+ * Execute pipeline pattern - chain agents in sequence
+ */
+export async function pipeline(bus, options) {
+    const initiatorId = resolveAgentId(options.initiator);
+    let currentPayload = options.input;
+    let lastResponse;
+    for (const stage of options.stages) {
+        const stageId = resolveAgentId(stage);
+        lastResponse = await requestFromAgent(bus, initiatorId, stageId, currentPayload, {
+            ...(options.stageTimeout !== undefined && { timeout: options.stageTimeout }),
+        });
+        currentPayload = lastResponse.payload;
+    }
+    return lastResponse;
+}
+/**
+ * Initiate a handoff to another agent
+ */
+export async function initiateHandoff(bus, options) {
+    const handoffId = generateHandoffId();
+    const fromAgentId = resolveAgentId(options.fromAgent);
+    const toAgentId = resolveAgentId(options.toAgent);
+    const request = {
+        id: handoffId,
+        fromAgent: fromAgentId,
+        toAgent: toAgentId,
+        context: options.context,
+        timestamp: new Date(),
+        ...(options.reason !== undefined && { reason: options.reason }),
+        ...(options.timeout !== undefined && { timeout: options.timeout }),
+        ...(options.previousAttempt !== undefined && { previousAttempt: options.previousAttempt }),
+        ...(options.onTimeout !== undefined && { onTimeout: options.onTimeout }),
+    };
+    // Register handoff in bus
+    bus.registerHandoff(request);
+    // Send handoff request message
+    const message = {
+        id: generateMessageId(),
+        type: 'handoff',
+        sender: fromAgentId,
+        recipient: toAgentId,
+        payload: {
+            action: 'request',
+            handoffId,
+            context: options.context,
+            reason: options.reason,
+        },
+        timestamp: new Date(),
+        correlationId: handoffId,
+    };
+    await bus.send(message);
+    return { handoffId, status: 'pending' };
+}
+/**
+ * Accept a pending handoff
+ */
+export async function acceptHandoff(bus, handoffId, agentId) {
+    const status = bus.getHandoffStatus(handoffId);
+    if (!status) {
+        throw new Error('Handoff not found');
+    }
+    if (status !== 'pending') {
+        throw new Error(`Cannot accept handoff in '${status}' state`);
+    }
+    bus.updateHandoffStatus(handoffId, 'accepted');
+    // Get the handoff request to find the initiating agent
+    const request = bus.getHandoffRequest(handoffId);
+    if (request) {
+        const acceptMessage = {
+            id: generateMessageId(),
+            type: 'handoff',
+            sender: agentId,
+            recipient: request.fromAgent,
+            payload: {
+                action: 'accepted',
+                handoffId,
+            },
+            timestamp: new Date(),
+            correlationId: handoffId,
+        };
+        await bus.send(acceptMessage);
+    }
+    return { handoffId, status: 'accepted' };
+}
+/**
+ * Reject a pending handoff
+ */
+export async function rejectHandoff(bus, handoffId, agentId, options) {
+    const status = bus.getHandoffStatus(handoffId);
+    if (!status) {
+        throw new Error('Handoff not found');
+    }
+    bus.updateHandoffStatus(handoffId, 'rejected');
+    // Get the handoff request to find the initiating agent
+    const request = bus.getHandoffRequest(handoffId);
+    if (request) {
+        const rejectMessage = {
+            id: generateMessageId(),
+            type: 'handoff',
+            sender: agentId,
+            recipient: request.fromAgent,
+            payload: {
+                action: 'rejected',
+                handoffId,
+                ...(options?.reason !== undefined && { reason: options.reason }),
+            },
+            timestamp: new Date(),
+            correlationId: handoffId,
+        };
+        await bus.send(rejectMessage);
+    }
+    return {
+        handoffId,
+        status: 'rejected',
+        ...(options?.reason !== undefined && { reason: options.reason }),
+    };
+}
+/**
+ * Complete a handoff (mark work as done)
+ */
+export async function completeHandoff(bus, handoffId, agentId, options) {
+    const status = bus.getHandoffStatus(handoffId);
+    if (!status) {
+        throw new Error('Handoff not found');
+    }
+    if (status !== 'accepted') {
+        throw new Error('Handoff not accepted');
+    }
+    bus.updateHandoffStatus(handoffId, 'completed');
+    // Get the handoff request to find the initiating agent
+    const request = bus.getHandoffRequest(handoffId);
+    if (request) {
+        const completeMessage = {
+            id: generateMessageId(),
+            type: 'handoff',
+            sender: agentId,
+            recipient: request.fromAgent,
+            payload: {
+                action: 'completed',
+                handoffId,
+                result: options?.result,
+            },
+            timestamp: new Date(),
+            correlationId: handoffId,
+        };
+        await bus.send(completeMessage);
+    }
+    return {
+        handoffId,
+        status: 'completed',
+        result: options?.result,
+        completedAt: new Date(),
+    };
+}
+//# sourceMappingURL=agent-comms.js.map