agent-relay 1.3.0 → 1.3.2

package/dist/daemon/consensus.js

@@ -0,0 +1,632 @@
+/**
+ * Agent Consensus Mechanism
+ *
+ * Enables distributed decision-making across multiple agents.
+ * Inspired by russian-code-ts roadmap: "Consensus-based decision making"
+ *
+ * Consensus Types:
+ * 1. Majority Vote - Simple >50% agreement
+ * 2. Supermajority - 2/3 or configurable threshold
+ * 3. Unanimous - All participants must agree
+ * 4. Weighted - Votes weighted by agent role/expertise
+ * 5. Quorum - Minimum participation required
+ *
+ * Use Cases:
+ * - Code review approval (2+ agents approve)
+ * - Architecture decisions (lead + majority)
+ * - Deployment gates (all critical agents agree)
+ * - Task assignment (weighted by expertise)
+ */
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+// =============================================================================
+// Default Configuration
+// =============================================================================
+const DEFAULT_CONFIG = {
+    defaultTimeoutMs: 5 * 60 * 1000, // 5 minutes
+    defaultConsensusType: 'majority',
+    defaultThreshold: 0.67, // 2/3 for supermajority
+    allowVoteChange: true,
+    autoResolve: true,
+    broadcastProposals: true,
+};
+// =============================================================================
+// Consensus Engine
+// =============================================================================
+export class ConsensusEngine extends EventEmitter {
+    config;
+    proposals = new Map();
+    expiryTimers = new Map();
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // ===========================================================================
+    // Proposal Management
+    // ===========================================================================
+    /**
+     * Create a new proposal.
+     */
+    createProposal(options) {
+        const id = `prop_${Date.now()}_${randomUUID().substring(0, 8)}`;
+        const now = Date.now();
+        const timeoutMs = options.timeoutMs ?? this.config.defaultTimeoutMs;
+        const proposal = {
+            id,
+            title: options.title,
+            description: options.description,
+            proposer: options.proposer,
+            consensusType: options.consensusType ?? this.config.defaultConsensusType,
+            participants: options.participants,
+            quorum: options.quorum,
+            threshold: options.threshold ?? this.config.defaultThreshold,
+            weights: options.weights,
+            createdAt: now,
+            expiresAt: now + timeoutMs,
+            status: 'pending',
+            votes: [],
+            metadata: options.metadata,
+            thread: options.thread ?? `consensus-${id}`,
+        };
+        this.proposals.set(id, proposal);
+        this.scheduleExpiry(proposal);
+        this.emit('proposal:created', proposal);
+        return proposal;
+    }
+    /**
+     * Submit a vote on a proposal.
+     */
+    vote(proposalId, agent, value, reason) {
+        const proposal = this.proposals.get(proposalId);
+        if (!proposal) {
+            return { success: false, error: 'Proposal not found' };
+        }
+        if (proposal.status !== 'pending') {
+            return { success: false, error: `Proposal is ${proposal.status}` };
+        }
+        if (!proposal.participants.includes(agent)) {
+            return { success: false, error: 'Agent not a participant' };
+        }
+        if (Date.now() > proposal.expiresAt) {
+            this.expireProposal(proposal);
+            return { success: false, error: 'Proposal has expired' };
+        }
+        // Check for existing vote
+        const existingVoteIndex = proposal.votes.findIndex(v => v.agent === agent);
+        if (existingVoteIndex >= 0) {
+            if (!this.config.allowVoteChange) {
+                return { success: false, error: 'Vote already cast and changes not allowed' };
+            }
+            // Remove existing vote
+            proposal.votes.splice(existingVoteIndex, 1);
+        }
+        // Determine vote weight
+        const weight = this.getAgentWeight(proposal, agent);
+        const vote = {
+            agent,
+            value,
+            weight,
+            reason,
+            timestamp: Date.now(),
+        };
+        proposal.votes.push(vote);
+        this.emit('proposal:voted', proposal, vote);
+        // Check for auto-resolution
+        if (this.config.autoResolve) {
+            const result = this.calculateResult(proposal);
+            if (this.canResolveEarly(proposal, result)) {
+                this.resolveProposal(proposal, result);
+            }
+        }
+        return { success: true, proposal };
+    }
+    /**
+     * Get a proposal by ID.
+     */
+    getProposal(proposalId) {
+        return this.proposals.get(proposalId) ?? null;
+    }
+    /**
+     * Get all proposals for an agent (as participant or proposer).
+     */
+    getProposalsForAgent(agent) {
+        const results = [];
+        for (const proposal of this.proposals.values()) {
+            if (proposal.proposer === agent || proposal.participants.includes(agent)) {
+                results.push(proposal);
+            }
+        }
+        return results;
+    }
+    /**
+     * Get pending proposals awaiting an agent's vote.
+     */
+    getPendingVotesForAgent(agent) {
+        const results = [];
+        for (const proposal of this.proposals.values()) {
+            if (proposal.status !== 'pending')
+                continue;
+            if (!proposal.participants.includes(agent))
+                continue;
+            if (proposal.votes.some(v => v.agent === agent))
+                continue;
+            results.push(proposal);
+        }
+        return results;
+    }
+    /**
+     * Cancel a proposal (only proposer can cancel).
+     */
+    cancelProposal(proposalId, agent) {
+        const proposal = this.proposals.get(proposalId);
+        if (!proposal) {
+            return { success: false, error: 'Proposal not found' };
+        }
+        if (proposal.proposer !== agent) {
+            return { success: false, error: 'Only proposer can cancel' };
+        }
+        if (proposal.status !== 'pending') {
+            return { success: false, error: `Proposal is ${proposal.status}` };
+        }
+        proposal.status = 'cancelled';
+        this.clearExpiryTimer(proposalId);
+        this.emit('proposal:cancelled', proposal);
+        return { success: true };
+    }
+    /**
+     * Force resolve a proposal (for admin/system use).
+     */
+    forceResolve(proposalId) {
+        const proposal = this.proposals.get(proposalId);
+        if (!proposal || proposal.status !== 'pending')
+            return null;
+        const result = this.calculateResult(proposal);
+        this.resolveProposal(proposal, result);
+        return result;
+    }
+    // ===========================================================================
+    // Consensus Calculation
+    // ===========================================================================
+    /**
+     * Calculate current consensus result.
+     */
+    calculateResult(proposal) {
+        let approveWeight = 0;
+        let rejectWeight = 0;
+        let abstainWeight = 0;
+        for (const vote of proposal.votes) {
+            switch (vote.value) {
+                case 'approve':
+                    approveWeight += vote.weight;
+                    break;
+                case 'reject':
+                    rejectWeight += vote.weight;
+                    break;
+                case 'abstain':
+                    abstainWeight += vote.weight;
+                    break;
+            }
+        }
+        const totalWeight = this.getTotalWeight(proposal);
+        const votedWeight = approveWeight + rejectWeight + abstainWeight;
+        const participation = totalWeight > 0 ? votedWeight / totalWeight : 0;
+        const voters = new Set(proposal.votes.map(v => v.agent));
+        const nonVoters = proposal.participants.filter(p => !voters.has(p));
+        // Check quorum
+        const quorumRequired = proposal.quorum ?? Math.ceil(proposal.participants.length / 2);
+        const quorumMet = proposal.votes.length >= quorumRequired;
+        // Determine decision based on consensus type
+        const decision = this.determineDecision(proposal, {
+            approveWeight,
+            rejectWeight,
+            abstainWeight,
+            totalWeight,
+            votedWeight,
+            quorumMet,
+        });
+        return {
+            decision,
+            approveWeight,
+            rejectWeight,
+            abstainWeight,
+            participation,
+            quorumMet,
+            resolvedAt: Date.now(),
+            nonVoters,
+        };
+    }
+    /**
+     * Determine decision based on consensus type and votes.
+     */
+    determineDecision(proposal, counts) {
+        const { approveWeight, rejectWeight, votedWeight, quorumMet } = counts;
+        switch (proposal.consensusType) {
+            case 'unanimous': {
+                // All participants must approve - any reject makes it impossible
+                const hasReject = proposal.votes.some(v => v.value === 'reject');
+                if (hasReject)
+                    return 'rejected';
+                if (proposal.votes.length < proposal.participants.length) {
+                    return 'no_consensus';
+                }
+                const allApprove = proposal.votes.every(v => v.value === 'approve');
+                return allApprove ? 'approved' : 'rejected';
+            }
+            case 'supermajority': {
+                const threshold = proposal.threshold ?? this.config.defaultThreshold;
+                if (votedWeight === 0)
+                    return 'no_consensus';
+                const approveRatio = approveWeight / votedWeight;
+                if (approveRatio >= threshold)
+                    return 'approved';
+                const rejectRatio = rejectWeight / votedWeight;
+                if (rejectRatio > (1 - threshold))
+                    return 'rejected';
+                return 'no_consensus';
+            }
+            case 'quorum': {
+                if (!quorumMet)
+                    return 'no_consensus';
+                // Fall through to majority
+            }
+            // eslint-disable-next-line no-fallthrough
+            case 'majority': {
+                if (votedWeight === 0)
+                    return 'no_consensus';
+                if (approveWeight > rejectWeight)
+                    return 'approved';
+                if (rejectWeight > approveWeight)
+                    return 'rejected';
+                return 'no_consensus'; // Tie
+            }
+            case 'weighted': {
+                // Same as majority but weights are already applied
+                if (votedWeight === 0)
+                    return 'no_consensus';
+                if (approveWeight > rejectWeight)
+                    return 'approved';
+                if (rejectWeight > approveWeight)
+                    return 'rejected';
+                return 'no_consensus';
+            }
+            default:
+                return 'no_consensus';
+        }
+    }
+    /**
+     * Check if proposal can be resolved early (consensus mathematically certain).
+     */
+    canResolveEarly(proposal, result) {
+        const totalWeight = this.getTotalWeight(proposal);
+        const remainingWeight = totalWeight - (result.approveWeight + result.rejectWeight + result.abstainWeight);
+        switch (proposal.consensusType) {
+            case 'unanimous':
+                // Can resolve early if anyone rejects
+                return proposal.votes.some(v => v.value === 'reject') ||
+                    proposal.votes.length === proposal.participants.length;
+            case 'supermajority': {
+                const threshold = proposal.threshold ?? this.config.defaultThreshold;
+                const votedWeight = result.approveWeight + result.rejectWeight + result.abstainWeight;
+                // Approved if approve ratio already exceeds threshold
+                if (votedWeight > 0 && result.approveWeight / votedWeight >= threshold) {
+                    // Check if remaining votes can't change outcome
+                    return (result.approveWeight / (votedWeight + remainingWeight)) >= threshold;
+                }
+                // Rejected if reject ratio exceeds (1 - threshold)
+                if (votedWeight > 0 && result.rejectWeight / votedWeight > (1 - threshold)) {
+                    return true;
+                }
+                return false;
+            }
+            case 'majority':
+            case 'weighted':
+                // Can resolve if one side has >50% of total weight
+                return result.approveWeight > totalWeight / 2 ||
+                    result.rejectWeight > totalWeight / 2;
+            case 'quorum':
+                // Need quorum first
+                if (!result.quorumMet)
+                    return false;
+                // Then same as majority
+                return result.approveWeight > totalWeight / 2 ||
+                    result.rejectWeight > totalWeight / 2;
+            default:
+                return false;
+        }
+    }
+    // ===========================================================================
+    // Weight Management
+    // ===========================================================================
+    /**
+     * Get weight for an agent in a proposal.
+     */
+    getAgentWeight(proposal, agent) {
+        if (proposal.weights) {
+            const weightConfig = proposal.weights.find(w => w.agent === agent);
+            if (weightConfig)
+                return weightConfig.weight;
+        }
+        return 1; // Default weight
+    }
+    /**
+     * Get total weight of all participants.
+     */
+    getTotalWeight(proposal) {
+        let total = 0;
+        for (const participant of proposal.participants) {
+            total += this.getAgentWeight(proposal, participant);
+        }
+        return total;
+    }
+    // ===========================================================================
+    // Lifecycle Management
+    // ===========================================================================
+    /**
+     * Resolve a proposal with result.
+     */
+    resolveProposal(proposal, result) {
+        proposal.status = result.decision === 'approved' ? 'approved' :
+            result.decision === 'rejected' ? 'rejected' : 'expired';
+        proposal.result = result;
+        this.clearExpiryTimer(proposal.id);
+        this.emit('proposal:resolved', proposal, result);
+    }
+    /**
+     * Expire a proposal.
+     */
+    expireProposal(proposal) {
+        if (proposal.status !== 'pending')
+            return;
+        const result = this.calculateResult(proposal);
+        proposal.status = 'expired';
+        proposal.result = result;
+        this.clearExpiryTimer(proposal.id);
+        this.emit('proposal:expired', proposal);
+    }
+    /**
+     * Schedule expiry timer for a proposal.
+     */
+    scheduleExpiry(proposal) {
+        const timeoutMs = proposal.expiresAt - Date.now();
+        if (timeoutMs <= 0) {
+            this.expireProposal(proposal);
+            return;
+        }
+        const timer = setTimeout(() => {
+            this.expireProposal(proposal);
+        }, timeoutMs);
+        timer.unref(); // Don't prevent process exit
+        this.expiryTimers.set(proposal.id, timer);
+    }
+    /**
+     * Clear expiry timer for a proposal.
+     */
+    clearExpiryTimer(proposalId) {
+        const timer = this.expiryTimers.get(proposalId);
+        if (timer) {
+            clearTimeout(timer);
+            this.expiryTimers.delete(proposalId);
+        }
+    }
+    /**
+     * Cleanup all timers (for shutdown).
+     */
+    cleanup() {
+        for (const timer of this.expiryTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.expiryTimers.clear();
+    }
+    // ===========================================================================
+    // Statistics
+    // ===========================================================================
+    /**
+     * Get consensus statistics.
+     */
+    getStats() {
+        let pending = 0, approved = 0, rejected = 0, expired = 0, cancelled = 0;
+        let totalParticipation = 0;
+        let resolvedCount = 0;
+        for (const proposal of this.proposals.values()) {
+            switch (proposal.status) {
+                case 'pending':
+                    pending++;
+                    break;
+                case 'approved':
+                    approved++;
+                    break;
+                case 'rejected':
+                    rejected++;
+                    break;
+                case 'expired':
+                    expired++;
+                    break;
+                case 'cancelled':
+                    cancelled++;
+                    break;
+            }
+            if (proposal.result) {
+                totalParticipation += proposal.result.participation;
+                resolvedCount++;
+            }
+        }
+        return {
+            total: this.proposals.size,
+            pending,
+            approved,
+            rejected,
+            expired,
+            cancelled,
+            avgParticipation: resolvedCount > 0 ? totalParticipation / resolvedCount : 0,
+        };
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a consensus engine with the given configuration.
+ */
+export function createConsensusEngine(config) {
+    return new ConsensusEngine(config);
+}
+// =============================================================================
+// Relay Integration Helpers
+// =============================================================================
+/**
+ * Format a proposal as a relay message for broadcasting.
+ */
+export function formatProposalMessage(proposal) {
+    const lines = [
+        `📋 **PROPOSAL: ${proposal.title}**`,
+        `ID: ${proposal.id}`,
+        `From: ${proposal.proposer}`,
+        `Type: ${proposal.consensusType}`,
+        `Expires: ${new Date(proposal.expiresAt).toISOString()}`,
+        '',
+        proposal.description,
+        '',
+        `Participants: ${proposal.participants.join(', ')}`,
+        '',
+        'Reply with: VOTE <proposal-id> <approve|reject|abstain> [reason]',
+    ];
+    return lines.join('\n');
+}
+/**
+ * Parse a vote command from a relay message.
+ */
+export function parseVoteCommand(message) {
+    const match = message.match(/^VOTE\s+(\S+)\s+(approve|reject|abstain)(?:\s+(.+))?$/i);
+    if (!match)
+        return null;
+    return {
+        proposalId: match[1],
+        value: match[2].toLowerCase(),
+        reason: match[3]?.trim(),
+    };
+}
+/**
+ * Format a consensus result as a relay message.
+ */
+export function formatResultMessage(proposal, result) {
+    const statusEmoji = result.decision === 'approved' ? '✅' :
+        result.decision === 'rejected' ? '❌' : '⏳';
+    const lines = [
+        `${statusEmoji} **CONSENSUS RESULT: ${proposal.title}**`,
+        `Decision: ${result.decision.toUpperCase()}`,
+        `Participation: ${(result.participation * 100).toFixed(1)}%`,
+        '',
+        `Approve: ${result.approveWeight} | Reject: ${result.rejectWeight} | Abstain: ${result.abstainWeight}`,
+    ];
+    if (result.nonVoters.length > 0) {
+        lines.push(`Non-voters: ${result.nonVoters.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Parse a PROPOSE command from a relay message.
+ *
+ * Format:
+ * ```
+ * PROPOSE: Title of the proposal
+ * TYPE: majority|supermajority|unanimous|weighted|quorum
+ * PARTICIPANTS: Agent1, Agent2, Agent3
+ * DESCRIPTION: Detailed description of what is being proposed
+ * TIMEOUT: 3600000 (optional, in milliseconds)
+ * QUORUM: 3 (optional, minimum votes)
+ * THRESHOLD: 0.67 (optional, for supermajority)
+ * ```
+ */
+export function parseProposalCommand(message) {
+    // Check if message starts with PROPOSE:
+    if (!message.trim().startsWith('PROPOSE:')) {
+        return null;
+    }
+    const lines = message.split('\n').map(line => line.trim());
+    // Parse each field
+    let title;
+    let description;
+    let participants;
+    let consensusType = 'majority';
+    let timeoutMs;
+    let quorum;
+    let threshold;
+    let inDescription = false;
+    const descriptionLines = [];
+    for (const line of lines) {
+        if (line.startsWith('PROPOSE:')) {
+            title = line.substring('PROPOSE:'.length).trim();
+            inDescription = false;
+        }
+        else if (line.startsWith('TYPE:')) {
+            const type = line.substring('TYPE:'.length).trim().toLowerCase();
+            if (['majority', 'supermajority', 'unanimous', 'weighted', 'quorum'].includes(type)) {
+                consensusType = type;
+            }
+            inDescription = false;
+        }
+        else if (line.startsWith('PARTICIPANTS:')) {
+            const participantStr = line.substring('PARTICIPANTS:'.length).trim();
+            participants = participantStr.split(',').map(p => p.trim()).filter(p => p.length > 0);
+            inDescription = false;
+        }
+        else if (line.startsWith('DESCRIPTION:')) {
+            description = line.substring('DESCRIPTION:'.length).trim();
+            inDescription = true;
+        }
+        else if (line.startsWith('TIMEOUT:')) {
+            const val = parseInt(line.substring('TIMEOUT:'.length).trim(), 10);
+            if (!isNaN(val) && val > 0) {
+                timeoutMs = val;
+            }
+            inDescription = false;
+        }
+        else if (line.startsWith('QUORUM:')) {
+            const val = parseInt(line.substring('QUORUM:'.length).trim(), 10);
+            if (!isNaN(val) && val > 0) {
+                quorum = val;
+            }
+            inDescription = false;
+        }
+        else if (line.startsWith('THRESHOLD:')) {
+            const val = parseFloat(line.substring('THRESHOLD:'.length).trim());
+            if (!isNaN(val) && val > 0 && val <= 1) {
+                threshold = val;
+            }
+            inDescription = false;
+        }
+        else if (inDescription && line.length > 0) {
+            // Continue collecting description lines
+            descriptionLines.push(line);
+        }
+    }
+    // Append continuation lines to description
+    if (descriptionLines.length > 0 && description) {
+        description = description + '\n' + descriptionLines.join('\n');
+    }
+    // Validate required fields
+    if (!title || !participants || participants.length === 0) {
+        return null;
+    }
+    // Default description if not provided
+    if (!description) {
+        description = title;
+    }
+    return {
+        title,
+        description,
+        participants,
+        consensusType,
+        timeoutMs,
+        quorum,
+        threshold,
+    };
+}
+/**
+ * Check if a message is a consensus command (PROPOSE or VOTE).
+ */
+export function isConsensusCommand(message) {
+    const trimmed = message.trim();
+    return trimmed.startsWith('PROPOSE:') || /^VOTE\s+/i.test(trimmed);
+}
+//# sourceMappingURL=consensus.js.map

package/dist/daemon/delivery-tracker.d.ts

@@ -0,0 +1,34 @@
+import type { DeliverEnvelope, AckPayload, Envelope } from '../protocol/types.js';
+import type { StorageAdapter } from '../storage/adapter.js';
+export interface DeliveryReliabilityOptions {
+    /** How long to wait for an ACK before retrying (ms) */
+    ackTimeoutMs: number;
+    /** Maximum attempts (initial send counts as attempt 1) */
+    maxAttempts: number;
+    /** How long to keep retrying before dropping (ms) */
+    deliveryTtlMs: number;
+}
+export declare const DEFAULT_DELIVERY_OPTIONS: DeliveryReliabilityOptions;
+export interface DeliveryTrackerConnection {
+    id: string;
+    send(envelope: DeliverEnvelope): boolean;
+}
+export declare class DeliveryTracker {
+    private pendingDeliveries;
+    private deliveryOptions;
+    private storage?;
+    private getConnection;
+    constructor(options: {
+        storage?: StorageAdapter;
+        delivery?: Partial<DeliveryReliabilityOptions>;
+        getConnection: (id: string) => DeliveryTrackerConnection | undefined;
+    });
+    get pendingCount(): number;
+    track(target: DeliveryTrackerConnection, deliver: DeliverEnvelope): void;
+    handleAck(connectionId: string, ackId: string): void;
+    clearPendingForConnection(connectionId: string): void;
+    private scheduleRetry;
+    private markFailed;
+}
+export type AckEnvelope = Envelope<AckPayload>;
+//# sourceMappingURL=delivery-tracker.d.ts.map