agent-relay 1.3.1 → 1.3.3

package/dist/daemon/consensus-integration.js

@@ -0,0 +1,371 @@
+/**
+ * Consensus Integration for Agent Relay
+ *
+ * Integrates the consensus mechanism with the router/daemon.
+ * This is an optional feature that can be enabled to allow agents
+ * to participate in distributed decision-making.
+ *
+ * Usage:
+ * 1. Create a ConsensusIntegration with the router and optional config
+ * 2. Call processIncomingMessage() on each received message to detect votes
+ * 3. Use createProposal() to start a new consensus vote
+ *
+ * Example:
+ * ```typescript
+ * const consensus = new ConsensusIntegration(router, { enabled: true });
+ *
+ * // Create a proposal
+ * consensus.createProposal({
+ *   title: 'Approve API design',
+ *   description: 'Should we proceed with the REST API design?',
+ *   proposer: 'Architect',
+ *   participants: ['Developer', 'Reviewer', 'Lead'],
+ *   consensusType: 'majority',
+ * });
+ *
+ * // Process incoming messages to detect votes
+ * consensus.processIncomingMessage(from, body);
+ * ```
+ */
+import { generateId } from '../utils/id-generator.js';
+import { ConsensusEngine, createConsensusEngine, formatProposalMessage, formatResultMessage, parseVoteCommand, parseProposalCommand, isConsensusCommand, } from './consensus.js';
+import { PROTOCOL_VERSION } from '../protocol/types.js';
+const DEFAULT_CONFIG = {
+    enabled: true,
+    autoBroadcast: true,
+    autoResultBroadcast: true,
+    logEvents: true,
+};
+// =============================================================================
+// Consensus Integration
+// =============================================================================
+/**
+ * Integrates consensus mechanism with the relay router.
+ * Provides automatic proposal broadcasting and vote detection.
+ */
+export class ConsensusIntegration {
+    config;
+    engine;
+    router;
+    log;
+    constructor(router, config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.router = router;
+        this.engine = createConsensusEngine(config.consensus);
+        // Setup logging
+        this.log = this.config.logEvents
+            ? (msg, data) => console.log(`[consensus] ${msg}`, data ?? '')
+            : () => { };
+        // Subscribe to engine events
+        this.setupEventHandlers();
+    }
+    /**
+     * Check if consensus is enabled.
+     */
+    get enabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Get the underlying consensus engine.
+     */
+    getEngine() {
+        return this.engine;
+    }
+    /**
+     * Create a new proposal and optionally broadcast to participants.
+     */
+    createProposal(options) {
+        if (!this.config.enabled) {
+            throw new Error('Consensus is not enabled');
+        }
+        const proposal = this.engine.createProposal({
+            ...options,
+            thread: `consensus-${options.title.toLowerCase().replace(/\s+/g, '-')}`,
+        });
+        this.log('Proposal created', { id: proposal.id, title: proposal.title });
+        return proposal;
+    }
+    /**
+     * Process an incoming message to detect and handle consensus commands.
+     * Handles both PROPOSE and VOTE commands.
+     */
+    processIncomingMessage(from, body) {
+        if (!this.config.enabled) {
+            return { isConsensusCommand: false };
+        }
+        // Check for PROPOSE command
+        const proposeCmd = parseProposalCommand(body);
+        if (proposeCmd) {
+            try {
+                const proposal = this.createProposal({
+                    ...proposeCmd,
+                    proposer: from,
+                });
+                this.log('Proposal created via command', {
+                    from,
+                    proposalId: proposal.id,
+                    title: proposal.title,
+                });
+                return {
+                    isConsensusCommand: true,
+                    type: 'propose',
+                    result: { success: true, proposal },
+                };
+            }
+            catch (err) {
+                return {
+                    isConsensusCommand: true,
+                    type: 'propose',
+                    result: {
+                        success: false,
+                        error: err instanceof Error ? err.message : 'Failed to create proposal',
+                    },
+                };
+            }
+        }
+        // Check for VOTE command
+        const voteCmd = parseVoteCommand(body);
+        if (voteCmd) {
+            const result = this.engine.vote(voteCmd.proposalId, from, voteCmd.value, voteCmd.reason);
+            this.log('Vote received', {
+                from,
+                proposalId: voteCmd.proposalId,
+                value: voteCmd.value,
+                success: result.success,
+            });
+            return { isConsensusCommand: true, type: 'vote', result };
+        }
+        return { isConsensusCommand: false };
+    }
+    /**
+     * Check if a message is a consensus command without processing it.
+     */
+    isConsensusMessage(body) {
+        return isConsensusCommand(body);
+    }
+    /**
+     * Get pending proposals for an agent.
+     */
+    getPendingVotes(agentName) {
+        return this.engine.getPendingVotesForAgent(agentName);
+    }
+    /**
+     * Get all proposals for an agent.
+     */
+    getProposals(agentName) {
+        return this.engine.getProposalsForAgent(agentName);
+    }
+    /**
+     * Get a specific proposal by ID.
+     */
+    getProposal(proposalId) {
+        return this.engine.getProposal(proposalId);
+    }
+    /**
+     * Cancel a proposal.
+     */
+    cancelProposal(proposalId, agentName) {
+        return this.engine.cancelProposal(proposalId, agentName);
+    }
+    /**
+     * Get consensus statistics.
+     */
+    getStats() {
+        return this.engine.getStats();
+    }
+    /**
+     * Cleanup resources.
+     */
+    cleanup() {
+        this.engine.cleanup();
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    /**
+     * Sync a proposal to the cloud dashboard.
+     *
+     * Auto-detects cloud settings from workspace env vars:
+     * - CLOUD_API_URL / AGENT_RELAY_CLOUD_URL - cloud URL
+     * - WORKSPACE_ID / AGENT_RELAY_WORKSPACE_ID - workspace ID
+     * - WORKSPACE_TOKEN / AGENT_RELAY_API_KEY - auth token
+     */
+    async syncToCloud(proposal, event) {
+        // Get cloud sync settings - check workspace env vars first, then agent-relay vars
+        const cloudUrl = this.config.cloudSync?.url
+            || process.env.CLOUD_API_URL
+            || process.env.AGENT_RELAY_CLOUD_URL;
+        const workspaceId = this.config.cloudSync?.workspaceId
+            || process.env.WORKSPACE_ID
+            || process.env.AGENT_RELAY_WORKSPACE_ID;
+        const token = this.config.cloudSync?.apiKey
+            || process.env.WORKSPACE_TOKEN
+            || process.env.AGENT_RELAY_API_KEY;
+        // Skip if no cloud URL configured
+        if (!cloudUrl) {
+            return;
+        }
+        // Skip if no workspace ID
+        if (!workspaceId) {
+            return;
+        }
+        try {
+            const url = `${cloudUrl}/api/daemons/consensus/sync`;
+            // Build headers - token is optional for localhost
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            if (token) {
+                headers['Authorization'] = `Bearer ${token}`;
+            }
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ proposal, event, workspaceId }),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.log(`Cloud sync failed: ${response.status} ${errorText}`);
+            }
+            else {
+                this.log(`Cloud sync: ${event} for proposal ${proposal.id}`);
+            }
+        }
+        catch (err) {
+            // Don't fail on cloud sync errors - just log them
+            this.log(`Cloud sync error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    setupEventHandlers() {
+        // Broadcast new proposals to participants
+        this.engine.on('proposal:created', (proposal) => {
+            if (this.config.autoBroadcast) {
+                this.broadcastProposal(proposal);
+            }
+            // Sync to cloud dashboard
+            this.syncToCloud(proposal, 'created');
+        });
+        // Notify participants when someone votes
+        this.engine.on('proposal:voted', (proposal, vote) => {
+            this.log('Vote recorded', {
+                proposalId: proposal.id,
+                voter: vote.agent,
+                value: vote.value,
+            });
+            // Sync updated proposal to cloud dashboard
+            this.syncToCloud(proposal, 'voted');
+        });
+        // Broadcast results when resolved
+        this.engine.on('proposal:resolved', (proposal, result) => {
+            this.log('Proposal resolved', {
+                id: proposal.id,
+                decision: result.decision,
+                participation: `${(result.participation * 100).toFixed(1)}%`,
+            });
+            if (this.config.autoResultBroadcast) {
+                this.broadcastResult(proposal, result);
+            }
+            // Sync resolved proposal to cloud dashboard
+            this.syncToCloud(proposal, 'resolved');
+        });
+        // Log expired proposals
+        this.engine.on('proposal:expired', (proposal) => {
+            this.log('Proposal expired', { id: proposal.id, title: proposal.title });
+            // Sync expired proposal to cloud dashboard
+            this.syncToCloud(proposal, 'expired');
+        });
+        // Log cancelled proposals
+        this.engine.on('proposal:cancelled', (proposal) => {
+            this.log('Proposal cancelled', { id: proposal.id, title: proposal.title });
+            // Sync cancelled proposal to cloud dashboard
+            this.syncToCloud(proposal, 'cancelled');
+        });
+    }
+    /**
+     * Broadcast a proposal to all participants via the router.
+     */
+    broadcastProposal(proposal) {
+        const message = formatProposalMessage(proposal);
+        for (const participant of proposal.participants) {
+            this.sendToAgent(proposal.proposer, participant, message, proposal.thread);
+        }
+        this.log('Proposal broadcast', {
+            id: proposal.id,
+            recipients: proposal.participants.length,
+        });
+    }
+    /**
+     * Broadcast the result of a proposal to all participants.
+     */
+    broadcastResult(proposal, result) {
+        const message = formatResultMessage(proposal, result);
+        // Send to proposer
+        this.sendToAgent('_consensus', proposal.proposer, message, proposal.thread);
+        // Send to all participants
+        for (const participant of proposal.participants) {
+            if (participant !== proposal.proposer) {
+                this.sendToAgent('_consensus', participant, message, proposal.thread);
+            }
+        }
+        this.log('Result broadcast', {
+            id: proposal.id,
+            decision: result.decision,
+            recipients: proposal.participants.length,
+        });
+    }
+    /**
+     * Send a message to an agent via the router.
+     */
+    sendToAgent(from, to, body, thread) {
+        // Create a SEND envelope
+        const envelope = {
+            v: PROTOCOL_VERSION,
+            type: 'SEND',
+            id: generateId(),
+            ts: Date.now(),
+            from,
+            to,
+            payload: {
+                kind: 'action',
+                body,
+                thread,
+                data: {
+                    _isConsensusMessage: true,
+                    _consensusAction: 'proposal',
+                },
+            },
+        };
+        // Get the target connection and route
+        const target = this.router.getConnection(to);
+        if (target) {
+            // Use a mock connection for system messages
+            const mockFrom = {
+                id: `consensus-${generateId()}`,
+                agentName: from,
+                sessionId: 'consensus-system',
+                close: () => { },
+                send: () => true,
+                getNextSeq: () => 0,
+            };
+            // Route the message
+            this.router.route(mockFrom, envelope);
+        }
+        else {
+            this.log(`Target agent not connected: ${to}`);
+        }
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a consensus integration instance.
+ */
+export function createConsensusIntegration(router, config) {
+    return new ConsensusIntegration(router, config);
+}
+// =============================================================================
+// Re-exports for convenience
+// =============================================================================
+export { ConsensusEngine, createConsensusEngine, formatProposalMessage, formatResultMessage, parseVoteCommand, parseProposalCommand, isConsensusCommand, };
+//# sourceMappingURL=consensus-integration.js.map

package/dist/daemon/consensus.d.ts

@@ -0,0 +1,271 @@
+/**
+ * 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 { EventEmitter } from 'node:events';
+export type ConsensusType = 'majority' | 'supermajority' | 'unanimous' | 'weighted' | 'quorum';
+export type VoteValue = 'approve' | 'reject' | 'abstain';
+export type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled';
+export interface AgentWeight {
+    /** Agent name */
+    agent: string;
+    /** Vote weight (default: 1) */
+    weight: number;
+    /** Agent role for context */
+    role?: string;
+}
+export interface Vote {
+    /** Voting agent */
+    agent: string;
+    /** Vote value */
+    value: VoteValue;
+    /** Vote weight (resolved at vote time) */
+    weight: number;
+    /** Optional reasoning */
+    reason?: string;
+    /** Vote timestamp */
+    timestamp: number;
+}
+export interface Proposal {
+    /** Unique proposal ID */
+    id: string;
+    /** Proposal title/subject */
+    title: string;
+    /** Detailed description */
+    description: string;
+    /** Proposing agent */
+    proposer: string;
+    /** Consensus type required */
+    consensusType: ConsensusType;
+    /** Agents allowed to vote */
+    participants: string[];
+    /** Minimum votes required (for quorum) */
+    quorum?: number;
+    /** Threshold for supermajority (0-1, default 0.67) */
+    threshold?: number;
+    /** Agent weights (for weighted voting) */
+    weights?: AgentWeight[];
+    /** Proposal creation timestamp */
+    createdAt: number;
+    /** Expiry timestamp */
+    expiresAt: number;
+    /** Current status */
+    status: ProposalStatus;
+    /** Collected votes */
+    votes: Vote[];
+    /** Result details (set when resolved) */
+    result?: ConsensusResult;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+    /** Thread ID for relay messages */
+    thread?: string;
+}
+export interface ConsensusResult {
+    /** Final decision */
+    decision: 'approved' | 'rejected' | 'no_consensus';
+    /** Total approve weight */
+    approveWeight: number;
+    /** Total reject weight */
+    rejectWeight: number;
+    /** Total abstain weight */
+    abstainWeight: number;
+    /** Participation rate (0-1) */
+    participation: number;
+    /** Whether quorum was met */
+    quorumMet: boolean;
+    /** Resolution timestamp */
+    resolvedAt: number;
+    /** Agents who didn't vote */
+    nonVoters: string[];
+}
+export interface ConsensusConfig {
+    /** Default proposal timeout in ms (default: 5 minutes) */
+    defaultTimeoutMs: number;
+    /** Default consensus type */
+    defaultConsensusType: ConsensusType;
+    /** Default supermajority threshold */
+    defaultThreshold: number;
+    /** Allow vote changes before resolution */
+    allowVoteChange: boolean;
+    /** Auto-resolve when consensus is mathematically certain */
+    autoResolve: boolean;
+    /** Broadcast proposals to all participants */
+    broadcastProposals: boolean;
+}
+export interface ConsensusEvents {
+    'proposal:created': (proposal: Proposal) => void;
+    'proposal:voted': (proposal: Proposal, vote: Vote) => void;
+    'proposal:resolved': (proposal: Proposal, result: ConsensusResult) => void;
+    'proposal:expired': (proposal: Proposal) => void;
+    'proposal:cancelled': (proposal: Proposal) => void;
+}
+export declare class ConsensusEngine extends EventEmitter {
+    private config;
+    private proposals;
+    private expiryTimers;
+    constructor(config?: Partial<ConsensusConfig>);
+    /**
+     * Create a new proposal.
+     */
+    createProposal(options: {
+        title: string;
+        description: string;
+        proposer: string;
+        participants: string[];
+        consensusType?: ConsensusType;
+        timeoutMs?: number;
+        quorum?: number;
+        threshold?: number;
+        weights?: AgentWeight[];
+        metadata?: Record<string, unknown>;
+        thread?: string;
+    }): Proposal;
+    /**
+     * Submit a vote on a proposal.
+     */
+    vote(proposalId: string, agent: string, value: VoteValue, reason?: string): {
+        success: boolean;
+        error?: string;
+        proposal?: Proposal;
+    };
+    /**
+     * Get a proposal by ID.
+     */
+    getProposal(proposalId: string): Proposal | null;
+    /**
+     * Get all proposals for an agent (as participant or proposer).
+     */
+    getProposalsForAgent(agent: string): Proposal[];
+    /**
+     * Get pending proposals awaiting an agent's vote.
+     */
+    getPendingVotesForAgent(agent: string): Proposal[];
+    /**
+     * Cancel a proposal (only proposer can cancel).
+     */
+    cancelProposal(proposalId: string, agent: string): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * Force resolve a proposal (for admin/system use).
+     */
+    forceResolve(proposalId: string): ConsensusResult | null;
+    /**
+     * Calculate current consensus result.
+     */
+    calculateResult(proposal: Proposal): ConsensusResult;
+    /**
+     * Determine decision based on consensus type and votes.
+     */
+    private determineDecision;
+    /**
+     * Check if proposal can be resolved early (consensus mathematically certain).
+     */
+    private canResolveEarly;
+    /**
+     * Get weight for an agent in a proposal.
+     */
+    private getAgentWeight;
+    /**
+     * Get total weight of all participants.
+     */
+    private getTotalWeight;
+    /**
+     * Resolve a proposal with result.
+     */
+    private resolveProposal;
+    /**
+     * Expire a proposal.
+     */
+    private expireProposal;
+    /**
+     * Schedule expiry timer for a proposal.
+     */
+    private scheduleExpiry;
+    /**
+     * Clear expiry timer for a proposal.
+     */
+    private clearExpiryTimer;
+    /**
+     * Cleanup all timers (for shutdown).
+     */
+    cleanup(): void;
+    /**
+     * Get consensus statistics.
+     */
+    getStats(): {
+        total: number;
+        pending: number;
+        approved: number;
+        rejected: number;
+        expired: number;
+        cancelled: number;
+        avgParticipation: number;
+    };
+}
+/**
+ * Create a consensus engine with the given configuration.
+ */
+export declare function createConsensusEngine(config?: Partial<ConsensusConfig>): ConsensusEngine;
+/**
+ * Format a proposal as a relay message for broadcasting.
+ */
+export declare function formatProposalMessage(proposal: Proposal): string;
+/**
+ * Parse a vote command from a relay message.
+ */
+export declare function parseVoteCommand(message: string): {
+    proposalId: string;
+    value: VoteValue;
+    reason?: string;
+} | null;
+/**
+ * Format a consensus result as a relay message.
+ */
+export declare function formatResultMessage(proposal: Proposal, result: ConsensusResult): string;
+export interface ParsedProposalCommand {
+    title: string;
+    description: string;
+    participants: string[];
+    consensusType: ConsensusType;
+    timeoutMs?: number;
+    quorum?: number;
+    threshold?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 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 declare function parseProposalCommand(message: string): ParsedProposalCommand | null;
+/**
+ * Check if a message is a consensus command (PROPOSE or VOTE).
+ */
+export declare function isConsensusCommand(message: string): boolean;
+//# sourceMappingURL=consensus.d.ts.map