@agent-relay/daemon 0.1.0

package/dist/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

package/dist/consensus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consensus.d.ts","sourceRoot":"","sources":["../src/consensus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,eAAe,GACf,WAAW,GACX,UAAU,GACV,QAAQ,CAAC;AAEb,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,UAAU,GACV,UAAU,GACV,SAAS,GACT,WAAW,CAAC;AAEhB,MAAM,WAAW,WAAW;IAC1B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,IAAI;IACnB,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,aAAa,EAAE,aAAa,CAAC;IAC7B,6BAA6B;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,sBAAsB;IACtB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,yCAAyC;IACzC,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,cAAc,CAAC;IACnD,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,oBAAoB,EAAE,aAAa,CAAC;IACpC,sCAAsC;IACtC,gBAAgB,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,eAAe,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,WAAW,EAAE,OAAO,CAAC;IACrB,8CAA8C;IAC9C,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,kBAAkB,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjD,gBAAgB,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC3D,mBAAmB,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC3E,kBAAkB,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjD,oBAAoB,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CACpD;AAmBD,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,YAAY,CAA0C;gBAElD,MAAM,GAAE,OAAO,CAAC,eAAe,CAAM;IASjD;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,aAAa,CAAC,EAAE,aAAa,CAAC;QAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,QAAQ;IA8BZ;;OAEG;IACH,IAAI,CACF,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,EAChB,MAAM,CAAC,EAAE,MAAM,GACd;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE;IAuD5D;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAIhD;;OAEG;IACH,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE;IAU/C;;OAEG;IACH,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE;IAWlD;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAsBvF;;OAEG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAaxD;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,eAAe;IAoDpD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA4DzB;;OAEG;IACH,OAAO,CAAC,eAAe;IA+CvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;OAEG;IACH,OAAO,IAAI,IAAI;IAWf;;OAEG;IACH,QAAQ,IAAI;QACV,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,CAAC;KAC1B;CA8BF;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAExF;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAgBhE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CASP;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,CAiBvF;AAMD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAqFlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG3D"}