@sparkleideas/swarm 3.0.0-alpha.7

package/src/federation-hub.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Federation Hub - Ephemeral Agent Coordination
+ *
+ * Provides cross-swarm coordination and ephemeral agent management
+ * for distributed multi-swarm architectures.
+ *
+ * Features:
+ * - Ephemeral agent spawning (short-lived, task-specific)
+ * - Cross-swarm communication and coordination
+ * - Federation protocol for distributed consensus
+ * - Resource allocation and load balancing
+ * - Agent lifecycle management with auto-cleanup
+ *
+ * Performance Targets:
+ * - Agent spawn: <50ms
+ * - Cross-swarm message: <100ms
+ * - Federation sync: <500ms
+ * - Auto-cleanup: Background, non-blocking
+ *
+ * Implements ADR-001: @sparkleideas/agentic-flow@alpha compatibility
+ * Implements ADR-003: Unified coordination engine
+ *
+ * @module @sparkleideas/swarm/federation-hub
+ * @version 3.0.0-alpha.1
+ */
+import { EventEmitter } from 'events';
+export type FederationId = string;
+export type SwarmId = string;
+export type EphemeralAgentId = string;
+export interface FederationConfig {
+    /** Federation identifier */
+    federationId?: FederationId;
+    /** Maximum ephemeral agents per swarm */
+    maxEphemeralAgents?: number;
+    /** Default TTL for ephemeral agents (ms) */
+    defaultTTL?: number;
+    /** Sync interval for federation state (ms) */
+    syncIntervalMs?: number;
+    /** Enable auto-cleanup of expired agents */
+    autoCleanup?: boolean;
+    /** Cleanup check interval (ms) */
+    cleanupIntervalMs?: number;
+    /** Cross-swarm communication timeout (ms) */
+    communicationTimeoutMs?: number;
+    /** Enable federation-wide consensus */
+    enableConsensus?: boolean;
+    /** Consensus quorum percentage */
+    consensusQuorum?: number;
+}
+export interface SwarmRegistration {
+    swarmId: SwarmId;
+    name: string;
+    endpoint?: string;
+    capabilities: string[];
+    maxAgents: number;
+    currentAgents: number;
+    status: 'active' | 'inactive' | 'degraded';
+    registeredAt: Date;
+    lastHeartbeat: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface EphemeralAgent {
+    id: EphemeralAgentId;
+    swarmId: SwarmId;
+    type: string;
+    task: string;
+    status: 'spawning' | 'active' | 'completing' | 'terminated';
+    ttl: number;
+    createdAt: Date;
+    expiresAt: Date;
+    completedAt?: Date;
+    result?: unknown;
+    error?: Error;
+    metadata?: Record<string, unknown>;
+}
+export interface SpawnEphemeralOptions {
+    /** Target swarm (auto-select if not specified) */
+    swarmId?: SwarmId;
+    /** Agent type */
+    type: string;
+    /** Task description */
+    task: string;
+    /** Time-to-live in ms (default from config) */
+    ttl?: number;
+    /** Required capabilities */
+    capabilities?: string[];
+    /** Priority for swarm selection */
+    priority?: 'low' | 'normal' | 'high' | 'critical';
+    /** Wait for completion */
+    waitForCompletion?: boolean;
+    /** Completion timeout (ms) */
+    completionTimeout?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface SpawnResult {
+    agentId: EphemeralAgentId;
+    swarmId: SwarmId;
+    status: 'spawned' | 'queued' | 'failed';
+    estimatedTTL: number;
+    result?: unknown;
+    error?: string;
+}
+export interface FederationMessage {
+    id: string;
+    type: 'broadcast' | 'direct' | 'consensus' | 'heartbeat';
+    sourceSwarmId: SwarmId;
+    targetSwarmId?: SwarmId;
+    payload: unknown;
+    timestamp: Date;
+    ttl?: number;
+}
+export interface ConsensusProposal {
+    id: string;
+    proposerId: SwarmId;
+    type: string;
+    value: unknown;
+    votes: Map<SwarmId, boolean>;
+    status: 'pending' | 'accepted' | 'rejected';
+    createdAt: Date;
+    expiresAt: Date;
+}
+export interface FederationStats {
+    federationId: FederationId;
+    totalSwarms: number;
+    activeSwarms: number;
+    totalEphemeralAgents: number;
+    activeEphemeralAgents: number;
+    completedAgents: number;
+    failedAgents: number;
+    avgAgentLifespanMs: number;
+    messagesExchanged: number;
+    consensusProposals: number;
+    uptime: number;
+}
+export interface FederationEvent {
+    type: FederationEventType;
+    federationId: FederationId;
+    swarmId?: SwarmId;
+    agentId?: EphemeralAgentId;
+    data?: unknown;
+    timestamp: Date;
+}
+export type FederationEventType = 'swarm_joined' | 'swarm_left' | 'swarm_degraded' | 'agent_spawned' | 'agent_completed' | 'agent_failed' | 'agent_expired' | 'message_sent' | 'message_received' | 'consensus_started' | 'consensus_completed' | 'federation_synced';
+export declare class FederationHub extends EventEmitter {
+    private config;
+    private swarms;
+    private ephemeralAgents;
+    private messages;
+    private proposals;
+    private syncInterval?;
+    private cleanupInterval?;
+    private startTime;
+    private stats;
+    /** Index: swarmId -> Set of agentIds */
+    private agentsBySwarm;
+    /** Index: status -> Set of agentIds */
+    private agentsByStatus;
+    constructor(config?: FederationConfig);
+    /**
+     * Add agent to indexes - O(1)
+     */
+    private addAgentToIndexes;
+    /**
+     * Remove agent from indexes - O(1)
+     */
+    private removeAgentFromIndexes;
+    /**
+     * Update agent status in index - O(1)
+     */
+    private updateAgentStatusIndex;
+    /**
+     * Get agents by swarm using index - O(k) where k is agents in swarm
+     */
+    private getAgentIdsBySwarm;
+    /**
+     * Get agents by status using index - O(k) where k is agents with status
+     */
+    private getAgentIdsByStatus;
+    /**
+     * Initialize the federation hub
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown the federation hub
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Register a swarm with the federation
+     */
+    registerSwarm(registration: Omit<SwarmRegistration, 'registeredAt' | 'lastHeartbeat'>): void;
+    /**
+     * Unregister a swarm from the federation
+     */
+    unregisterSwarm(swarmId: SwarmId): boolean;
+    /**
+     * Update swarm heartbeat
+     */
+    heartbeat(swarmId: SwarmId, currentAgents?: number): boolean;
+    /**
+     * Get all registered swarms
+     */
+    getSwarms(): SwarmRegistration[];
+    /**
+     * Get swarm by ID
+     */
+    getSwarm(swarmId: SwarmId): SwarmRegistration | undefined;
+    /**
+     * Spawn an ephemeral agent
+     */
+    spawnEphemeralAgent(options: SpawnEphemeralOptions): Promise<SpawnResult>;
+    /**
+     * Complete an ephemeral agent's task
+     */
+    completeAgent(agentId: EphemeralAgentId, result?: unknown): boolean;
+    /**
+     * Terminate an ephemeral agent
+     */
+    terminateAgent(agentId: EphemeralAgentId, error?: Error): Promise<boolean>;
+    /**
+     * Get ephemeral agent by ID
+     */
+    getAgent(agentId: EphemeralAgentId): EphemeralAgent | undefined;
+    /**
+     * Get all ephemeral agents
+     */
+    getAgents(swarmId?: SwarmId): EphemeralAgent[];
+    /**
+     * Get active ephemeral agents
+     */
+    getActiveAgents(swarmId?: SwarmId): EphemeralAgent[];
+    /**
+     * Send a message to another swarm
+     */
+    sendMessage(sourceSwarmId: SwarmId, targetSwarmId: SwarmId, payload: unknown): Promise<boolean>;
+    /**
+     * Broadcast a message to all swarms
+     */
+    broadcast(sourceSwarmId: SwarmId, payload: unknown): Promise<number>;
+    /**
+     * Get recent messages
+     */
+    getMessages(limit?: number): FederationMessage[];
+    /**
+     * Propose a value for federation-wide consensus
+     */
+    propose(proposerId: SwarmId, type: string, value: unknown, timeoutMs?: number): Promise<ConsensusProposal>;
+    /**
+     * Vote on a proposal
+     */
+    vote(swarmId: SwarmId, proposalId: string, approve: boolean): boolean;
+    /**
+     * Get proposal by ID
+     */
+    getProposal(proposalId: string): ConsensusProposal | undefined;
+    /**
+     * Get all pending proposals
+     */
+    getPendingProposals(): ConsensusProposal[];
+    /**
+     * Get federation statistics
+     */
+    getStats(): FederationStats;
+    private selectOptimalSwarm;
+    private getSwarmAgentCount;
+    private getActiveSwarmCount;
+    private waitForAgentCompletion;
+    private syncFederation;
+    private cleanupExpiredAgents;
+    private emitEvent;
+}
+/**
+ * Create a new Federation Hub instance
+ */
+export declare function createFederationHub(config?: FederationConfig): FederationHub;
+/**
+ * Get or create the default federation hub
+ */
+export declare function getDefaultFederationHub(): FederationHub;
+/**
+ * Reset the default federation hub
+ */
+export declare function resetDefaultFederationHub(): Promise<void>;
+//# sourceMappingURL=federation-hub.d.ts.map

package/src/federation-hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-hub.d.ts","sourceRoot":"","sources":["federation-hub.ts"],"names":[],"mappings":"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"}