@holoscript/framework 6.0.3

package/dist/negotiation/index.d.cts

@@ -0,0 +1,610 @@
+import { A as AgentManifest } from '../AgentManifest-CB4xM-Ma.cjs';
+
+/**
+ * @holoscript/core - Negotiation Type Definitions
+ *
+ * Types for agent negotiation, voting, and conflict resolution.
+ * Part of HoloScript v3.1 Agentic Choreography.
+ *
+ * @version 3.1.0
+ * @Sprint v3.1 (March 2026)
+ */
+
+/**
+ * Status of a negotiation session
+ */
+type NegotiationStatus = 'draft' | 'open' | 'proposing' | 'voting' | 'resolving' | 'resolved' | 'deadlock' | 'deadlocked' | 'timeout' | 'escalated' | 'failed' | 'cancelled';
+/**
+ * Voting mechanism type
+ */
+type VotingMechanism = 'majority' | 'supermajority' | 'weighted' | 'consensus' | 'ranked' | 'approval' | 'borda' | 'custom';
+/**
+ * Proposal status
+ */
+type ProposalStatus = 'pending' | 'submitted' | 'under_review' | 'accepted' | 'rejected' | 'withdrawn';
+/**
+ * Resolution outcome
+ */
+type ResolutionOutcome = 'winner_declared' | 'tie_broken' | 'consensus_reached' | 'deadlock' | 'timeout' | 'escalated' | 'quorum_not_met' | 'cancelled';
+/**
+ * Tie-breaker strategy
+ */
+type TieBreaker = 'random' | 'seniority' | 'priority' | 'proposer' | 'escalate';
+/**
+ * A proposal in a negotiation
+ */
+interface Proposal {
+    /** Unique proposal ID */
+    id: string;
+    /** Session this proposal belongs to */
+    sessionId?: string;
+    /** ID of the proposing agent */
+    proposerId?: string;
+    /** Proposal title */
+    title?: string;
+    /** Proposal description */
+    description?: string;
+    /** ID of the proposing agent (legacy) */
+    agentId: string;
+    /** Proposal content/value */
+    content: unknown;
+    /** Priority weight (higher = more important to proposer) */
+    priority: number;
+    /** Reasoning/justification */
+    reasoning?: string;
+    /** Resource requirements */
+    resources?: ResourceRequest[];
+    /** Time constraints */
+    timeline?: {
+        earliest?: number;
+        latest?: number;
+        duration?: number;
+    };
+    /** Proposal status */
+    status: ProposalStatus;
+    /** Submission timestamp */
+    submittedAt: number;
+    /** Last modified timestamp */
+    modifiedAt?: number;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for creating a proposal
+ */
+interface ProposalInput {
+    /** ID of the proposing agent */
+    proposerId: string;
+    /** Proposal title */
+    title: string;
+    /** Proposal description */
+    description?: string;
+    /** Proposal content/value */
+    content: unknown;
+    /** Priority weight */
+    priority?: number;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Resource request in a proposal
+ */
+interface ResourceRequest {
+    /** Resource type */
+    type: string;
+    /** Amount requested */
+    amount: number;
+    /** Unit of measurement */
+    unit?: string;
+    /** Whether exclusive access is needed */
+    exclusive?: boolean;
+}
+/**
+ * A vote cast by an agent
+ */
+interface Vote {
+    /** Unique vote ID */
+    id?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Voting agent ID */
+    agentId: string;
+    /** Ranked preferences (proposal IDs) */
+    ranking: string[];
+    /** Approval set (for approval voting) */
+    approvals?: string[];
+    /** Vote weight (determined by trust level) */
+    weight: number;
+    /** Optional vote reason/justification */
+    reason?: string;
+    /** Optional justification */
+    justification?: string;
+    /** Whether this is an abstention */
+    abstain?: boolean;
+    /** Vote timestamp */
+    timestamp: number;
+    /** If this vote was superseded by another */
+    supersededBy?: string;
+}
+/**
+ * Input for casting a vote
+ */
+interface VoteInput {
+    /** Voting agent ID */
+    agentId: string;
+    /** Ranked preferences */
+    ranking?: string[];
+    /** Approval set */
+    approvals?: string[];
+    /** Vote weight */
+    weight?: number;
+    /** Justification */
+    justification?: string;
+    /** Abstain from voting */
+    abstain?: boolean;
+}
+/**
+ * Vote tally result
+ */
+interface VoteTally {
+    /** Proposal ID */
+    proposalId: string;
+    /** Total votes received */
+    voteCount: number;
+    /** Weighted score */
+    weightedScore: number;
+    /** Approval count */
+    approvalCount?: number;
+    /** Borda points */
+    bordaPoints?: number;
+    /** Percentage of votes */
+    percentage: number;
+}
+/**
+ * Negotiation session configuration
+ */
+interface NegotiationConfig {
+    /** Voting mechanism */
+    mechanism: VotingMechanism;
+    /** Voting mechanism (alias) */
+    votingMechanism?: VotingMechanism;
+    /** Session timeout (ms) */
+    timeout?: number;
+    /** Proposal deadline (ms from start) */
+    proposalDeadline?: number;
+    /** Voting deadline (ms from start) */
+    votingDeadline?: number;
+    /** Maximum rounds before deadlock */
+    maxRounds?: number;
+    /** Tie-breaking strategy */
+    tieBreaker?: TieBreaker;
+    /** Minimum participation ratio */
+    quorum?: number;
+    /** Allow proposal amendments */
+    allowAmendments?: boolean;
+    /** Anonymous voting */
+    anonymousVoting?: boolean;
+    /** Allow delegation */
+    allowDelegation?: boolean;
+    /** Allow agents to abstain */
+    allowAbstain?: boolean;
+    /** Require justification for votes */
+    requireJustification?: boolean;
+    /** Auto-escalate on deadlock */
+    escalateOnDeadlock?: boolean;
+    /** Escalation target */
+    escalationTarget?: string;
+    /** Escalation path */
+    escalationPath?: string;
+}
+/**
+ * Negotiation session
+ */
+interface NegotiationSession {
+    /** Unique session ID */
+    id: string;
+    /** Negotiation topic */
+    topic: string;
+    /** Description */
+    description?: string;
+    /** Participating agent IDs (can be strings or full manifests) */
+    participants: (string | AgentManifest)[];
+    /** Session configuration */
+    config: NegotiationConfig;
+    /** Submitted proposals */
+    proposals: Proposal[];
+    /** Cast votes */
+    votes: Vote[];
+    /** Current status */
+    status: NegotiationStatus;
+    /** Current round number */
+    round: number;
+    /** Current round (alias) */
+    currentRound?: number;
+    /** Session creation time */
+    createdAt?: number;
+    /** Session start time */
+    startedAt: number;
+    /** Last activity timestamp */
+    lastActivityAt: number;
+    /** Deadline timestamp */
+    deadline?: number;
+    /** Resolution result */
+    resolution?: Resolution;
+    /** Session resolution timestamp */
+    resolvedAt?: number;
+    /** Session history/log */
+    history: NegotiationEvent[];
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Negotiation event for history
+ */
+interface NegotiationEvent {
+    /** Event type */
+    type: 'session_created' | 'session_started' | 'proposal_submitted' | 'proposal_amended' | 'proposal_withdrawn' | 'voting_started' | 'vote_cast' | 'round_complete' | 'resolution_reached' | 'deadlock_detected' | 'escalation_triggered' | 'session_cancelled';
+    /** Event timestamp */
+    timestamp: number;
+    /** Related agent ID */
+    agentId?: string;
+    /** Related proposal ID */
+    proposalId?: string;
+    /** Event details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Resolution of a negotiation
+ */
+interface Resolution {
+    /** Session ID */
+    sessionId?: string;
+    /** Winning proposal ID */
+    winnerId?: string;
+    /** Winning proposal */
+    winner?: Proposal;
+    /** Winning proposal (alias) */
+    winningProposal?: Proposal;
+    /** Final tallies */
+    tallies: VoteTally[];
+    /** Final tallies (alias) */
+    finalTallies?: VoteTally[];
+    /** Resolution outcome */
+    outcome: ResolutionOutcome;
+    /** Resolution mechanism used */
+    mechanism: VotingMechanism;
+    /** Number of rounds taken */
+    rounds: number;
+    /** Round (alias) */
+    round?: number;
+    /** Resolution timestamp */
+    resolvedAt: number;
+    /** Timestamp (alias) */
+    timestamp?: number;
+    /** Tie-breaker used (if any) */
+    tieBreakerUsed?: boolean;
+    /** Consensus level (0-1) */
+    consensusLevel?: number;
+    /** Dissenting agents */
+    dissenters?: string[];
+    /** Participation rate (0-1) */
+    participationRate?: number;
+    /** Escalation target */
+    escalatedTo?: string;
+    /** Notes */
+    notes?: string;
+}
+/**
+ * Events emitted by NegotiationProtocol
+ */
+interface NegotiationEvents {
+    'session:created': (session: NegotiationSession) => void;
+    'session:started': (session: NegotiationSession) => void;
+    'session:cancelled': (sessionId: string, reason: string) => void;
+    'proposal:submitted': (proposal: Proposal, session: NegotiationSession) => void;
+    'proposal:amended': (proposal: Proposal, session: NegotiationSession) => void;
+    'proposal:withdrawn': (proposalId: string, session: NegotiationSession) => void;
+    'voting:started': (session: NegotiationSession) => void;
+    'vote:cast': (vote: Vote, session: NegotiationSession) => void;
+    'round:complete': (round: number, session: NegotiationSession) => void;
+    'resolution:reached': (resolution: Resolution, session: NegotiationSession) => void;
+    'deadlock:detected': (session: NegotiationSession) => void;
+    'escalation:triggered': (session: NegotiationSession, target: string) => void;
+    sessionStarted: {
+        session: NegotiationSession;
+    };
+    proposalSubmitted: {
+        session: NegotiationSession;
+        proposal: Proposal;
+    };
+    voteReceived: {
+        session: NegotiationSession;
+        vote: Vote;
+    };
+    sessionResolved: {
+        session: NegotiationSession;
+        resolution: Resolution;
+    };
+}
+/**
+ * Options for initiating a negotiation session
+ */
+interface InitiateOptions {
+    /** Negotiation topic */
+    topic: string;
+    /** Description */
+    description?: string;
+    /** Participating agent IDs */
+    participants: string[];
+    /** Voting mechanism */
+    votingMechanism?: VotingMechanism;
+    /** Session timeout (ms) */
+    timeout?: number;
+    /** Quorum requirement (0-1) */
+    quorum?: number;
+    /** Maximum rounds */
+    maxRounds?: number;
+    /** Allow abstention */
+    allowAbstain?: boolean;
+    /** Require vote justification */
+    requireJustification?: boolean;
+    /** Tie-breaker strategy */
+    tieBreaker?: TieBreaker;
+    /** Escalation path */
+    escalationPath?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * @holoscript/core - Voting Mechanisms
+ *
+ * Implementations of various voting algorithms for agent negotiation.
+ * Part of HoloScript v3.1 Agentic Choreography.
+ *
+ * Supported mechanisms:
+ * - Majority: Simple majority wins
+ * - Supermajority: 2/3 threshold required
+ * - Weighted: Vote weight by trust level
+ * - Consensus: All must agree
+ * - Ranked Choice: Instant runoff voting
+ * - Approval: Multiple approval voting
+ * - Borda Count: Point-based ranking
+ *
+ * @version 3.1.0
+ * @Sprint v3.1 (March 2026)
+ */
+
+/**
+ * Result from a voting round
+ */
+interface VotingResult {
+    /** Final tallies */
+    tallies: VoteTally[];
+    /** Winner ID (if determined) */
+    winnerId?: string;
+    /** Whether resolution was reached */
+    resolved: boolean;
+    /** Outcome type */
+    outcome: ResolutionOutcome;
+    /** Tie detected */
+    tie?: boolean;
+    /** Eliminated proposals (for ranked choice) */
+    eliminated?: string[];
+    /** Consensus level (0-1) */
+    consensusLevel?: number;
+    /** Dissenters */
+    dissenters?: string[];
+}
+/**
+ * Voting mechanism handler interface
+ */
+interface VotingHandler {
+    /** Count votes and determine result */
+    count(votes: Vote[], proposals: Proposal[], config: NegotiationConfig, round: number): VotingResult;
+    /** Validate a vote for this mechanism */
+    validateVote(vote: Vote, proposals: Proposal[]): boolean;
+    /** Get required quorum for this mechanism */
+    getRequiredQuorum(config: NegotiationConfig): number;
+}
+/**
+ * Simple majority voting (>50% wins)
+ */
+declare const majorityHandler: VotingHandler;
+/**
+ * Supermajority voting (≥66.67% wins)
+ */
+declare const supermajorityHandler: VotingHandler;
+/**
+ * Weighted voting (trust-level based weights)
+ */
+declare const weightedHandler: VotingHandler;
+/**
+ * Consensus voting (all must agree)
+ */
+declare const consensusHandler: VotingHandler;
+/**
+ * Ranked choice voting with instant runoff
+ */
+declare const rankedHandler: VotingHandler;
+/**
+ * Approval voting (vote for multiple acceptable options)
+ */
+declare const approvalHandler: VotingHandler;
+/**
+ * Borda count voting (points by rank position)
+ */
+declare const bordaHandler: VotingHandler;
+/**
+ * Get handler for a voting mechanism
+ */
+declare function getVotingHandler(mechanism: VotingMechanism): VotingHandler;
+/**
+ * Check if quorum is met
+ */
+declare function checkQuorum(votes: Vote[], participants: number, config: NegotiationConfig, mechanism: VotingMechanism): boolean;
+/**
+ * Get trust-based vote weight
+ */
+declare function getTrustWeight(trustLevel: 'local' | 'verified' | 'external'): number;
+
+/**
+ * @holoscript/core - Negotiation Protocol
+ *
+ * Core protocol for multi-agent negotiation and consensus building.
+ * Manages negotiation sessions, proposals, voting, and resolution.
+ *
+ * Part of HoloScript v3.1 Agentic Choreography.
+ *
+ * @example
+ * ```typescript
+ * const protocol = new NegotiationProtocol();
+ *
+ * // Start a negotiation
+ * const session = await protocol.initiate({
+ *   topic: 'task-assignment',
+ *   participants: ['agent-1', 'agent-2', 'agent-3'],
+ *   votingMechanism: 'majority',
+ *   timeout: 60000,
+ * });
+ *
+ * // Submit proposals
+ * await protocol.propose(session.id, {
+ *   proposerId: 'agent-1',
+ *   title: 'Process sequentially',
+ *   description: 'Handle tasks one at a time',
+ *   content: { strategy: 'sequential' },
+ * });
+ *
+ * // Vote on proposals
+ * await protocol.vote(session.id, {
+ *   agentId: 'agent-2',
+ *   ranking: ['proposal-1'],
+ * });
+ *
+ * // Resolve when ready
+ * const resolution = await protocol.resolve(session.id);
+ * ```
+ *
+ * @version 3.1.0
+ * @Sprint v3.1 (March 2026)
+ */
+
+/**
+ * Audit log entry
+ */
+interface AuditEntry {
+    timestamp: number;
+    sessionId: string;
+    action: 'initiated' | 'proposal_submitted' | 'vote_cast' | 'resolved' | 'timeout' | 'escalated';
+    agentId?: string;
+    details: Record<string, unknown>;
+}
+/**
+ * Event handler type
+ */
+type EventHandler<T> = (data: T) => void | Promise<void>;
+/**
+ * NegotiationProtocol manages multi-agent negotiation sessions.
+ *
+ * Features:
+ * - Multiple voting mechanisms (majority, consensus, ranked, etc.)
+ * - Proposal lifecycle management
+ * - Quorum and deadline enforcement
+ * - Deadlock detection and escalation
+ * - Full audit logging
+ */
+declare class NegotiationProtocol {
+    private sessions;
+    private auditLog;
+    private deadlines;
+    private eventHandlers;
+    private sessionCounter;
+    private proposalCounter;
+    private voteCounter;
+    /**
+     * Initiate a new negotiation session
+     */
+    initiate(options: InitiateOptions): Promise<NegotiationSession>;
+    /**
+     * Submit a proposal to a session
+     */
+    propose(sessionId: string, input: ProposalInput): Promise<Proposal>;
+    /**
+     * Cast a vote in a session
+     */
+    vote(sessionId: string, input: VoteInput): Promise<Vote>;
+    /**
+     * Resolve a negotiation session
+     */
+    resolve(sessionId: string, force?: boolean): Promise<Resolution>;
+    /**
+     * Get session by ID
+     */
+    getSession(sessionId: string): NegotiationSession;
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions(): NegotiationSession[];
+    /**
+     * Get sessions for a specific agent
+     */
+    getAgentSessions(agentId: string): NegotiationSession[];
+    /**
+     * Cancel a session
+     */
+    cancel(sessionId: string, _reason?: string): Promise<void>;
+    /**
+     * Escalate a deadlocked session
+     */
+    escalate(sessionId: string): Promise<Resolution>;
+    /**
+     * Add a participant to an open session
+     */
+    addParticipant(sessionId: string, agentId: string): void;
+    /**
+     * Remove a participant from a session
+     */
+    removeParticipant(sessionId: string, agentId: string): void;
+    /**
+     * Subscribe to negotiation events
+     */
+    on<K extends keyof NegotiationEvents>(event: K, handler: EventHandler<NegotiationEvents[K]>): () => void;
+    /**
+     * Get audit log
+     */
+    getAuditLog(sessionId?: string): AuditEntry[];
+    /**
+     * Clear completed sessions older than maxAge
+     */
+    pruneOldSessions(maxAgeMs: number): number;
+    /**
+     * Reset protocol state (for testing)
+     */
+    reset(): void;
+    private generateSessionId;
+    private generateProposalId;
+    private generateVoteId;
+    private validateSessionOpen;
+    private validateParticipant;
+    private validateNotDuplicate;
+    private allVotesCast;
+    private tryAutoResolve;
+    private buildResolution;
+    private createFailedResolution;
+    private startDeadlineTimer;
+    private handleTimeout;
+    private clearDeadline;
+    private audit;
+    private emit;
+}
+/**
+ * Get the default NegotiationProtocol instance
+ */
+declare function getNegotiationProtocol(): NegotiationProtocol;
+/**
+ * Reset the default protocol instance (for testing)
+ */
+declare function resetNegotiationProtocol(): void;
+
+export { type AuditEntry, type InitiateOptions, type NegotiationConfig, type NegotiationEvents, NegotiationProtocol, type NegotiationSession, type NegotiationStatus, type Proposal, type ProposalInput, type ProposalStatus, type Resolution, type ResolutionOutcome, type TieBreaker, type Vote, type VoteInput, type VoteTally, type VotingHandler, type VotingMechanism, type VotingResult, approvalHandler, bordaHandler, checkQuorum, consensusHandler, getNegotiationProtocol, getTrustWeight, getVotingHandler, majorityHandler, rankedHandler, resetNegotiationProtocol, supermajorityHandler, weightedHandler };