agentic-flow 2.0.1-alpha → 2.0.1-alpha.2

package/dist/services/sona-service.d.ts

@@ -0,0 +1,191 @@
+/**
+ * SONA Service - Self-Optimizing Neural Architecture
+ *
+ * Production implementation based on vibecast test-ruvector-sona patterns
+ * Achieves +55.3% quality improvement with optimal configuration
+ *
+ * Key Performance Metrics:
+ * - 2211 ops/sec throughput
+ * - 18.07ms total overhead (40 layers)
+ * - 0.452ms per-layer cost
+ * - Sub-millisecond token latency
+ *
+ * Based on: https://github.com/ruvnet/vibecast/tree/claude/test-ruvector-sona-01Raj3Q3P4qjff4JGVipJhvz
+ */
+import { EventEmitter } from 'events';
+/**
+ * SONA Configuration Profiles
+ */
+export type SONAProfile = 'real-time' | 'batch' | 'research' | 'edge' | 'balanced' | 'custom';
+export interface SONAConfig {
+    profile?: SONAProfile;
+    hiddenDim: number;
+    embeddingDim: number;
+    microLoraRank: number;
+    baseLoraRank: number;
+    microLoraLr: number;
+    baseLoraLr: number;
+    ewcLambda: number;
+    patternClusters: number;
+    trajectoryCapacity: number;
+    backgroundIntervalMs: number;
+    qualityThreshold: number;
+    enableSimd: boolean;
+}
+export interface TrajectoryMetadata {
+    id: string;
+    embedding: number[];
+    route?: string;
+    contexts: string[];
+    steps: TrajectoryStep[];
+    startTime: number;
+    endTime?: number;
+    qualityScore?: number;
+}
+export interface TrajectoryStep {
+    activations: number[];
+    attentionWeights: number[];
+    reward: number;
+    timestamp: number;
+}
+export interface PatternMatch {
+    id: string;
+    centroid: number[];
+    clusterSize: number;
+    avgQuality: number;
+    patternType: string;
+    similarity: number;
+}
+/**
+ * SONA Service - Main orchestration class
+ */
+export declare class SONAService extends EventEmitter {
+    private engine;
+    private config;
+    private trajectories;
+    private stats;
+    constructor(config?: Partial<SONAConfig>);
+    /**
+     * Resolve configuration from profile or custom settings
+     */
+    private resolveConfig;
+    /**
+     * Begin a new trajectory
+     */
+    beginTrajectory(embedding: number[], route?: string): string;
+    /**
+     * Add a step to an active trajectory
+     */
+    addTrajectoryStep(trajectoryId: string, activations: number[], attentionWeights: number[], reward: number): void;
+    /**
+     * Add context to a trajectory
+     */
+    addTrajectoryContext(trajectoryId: string, contextId: string): void;
+    /**
+     * End a trajectory with quality score
+     */
+    endTrajectory(trajectoryId: string, qualityScore: number): void;
+    /**
+     * Apply Micro-LoRA to input
+     */
+    applyMicroLora(input: number[]): number[];
+    /**
+     * Apply Base-LoRA to layer
+     */
+    applyBaseLora(layerIndex: number, input: number[]): number[];
+    /**
+     * Find similar patterns
+     */
+    findPatterns(query: number[], k?: number): PatternMatch[];
+    /**
+     * Calculate cosine similarity between vectors
+     */
+    private calculateSimilarity;
+    /**
+     * Force learning cycle
+     */
+    forceLearn(): {
+        success: boolean;
+        patternsLearned: number;
+    };
+    /**
+     * Check if learning should be triggered
+     * Trigger forceLearn() when 80% of trajectory capacity is full
+     */
+    private checkLearningTrigger;
+    /**
+     * Tick for scheduled learning
+     */
+    tick(): void;
+    /**
+     * Get engine statistics
+     */
+    getEngineStats(): string;
+    /**
+     * Get service statistics
+     */
+    getStats(): {
+        config: SONAConfig;
+        engineEnabled: boolean;
+        trajectoryUtilization: number;
+        avgTrajectoryDuration: number;
+        opsPerSecond: number;
+        totalTrajectories: number;
+        activeTrajectories: number;
+        completedTrajectories: number;
+        totalLearningCycles: number;
+        avgQualityScore: number;
+        totalOpsProcessed: number;
+    };
+    /**
+     * Calculate average trajectory duration
+     */
+    private calculateAvgTrajectoryDuration;
+    /**
+     * Calculate operations per second
+     */
+    private calculateOpsPerSecond;
+    /**
+     * Enable/disable engine
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if engine is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Flush engine state
+     */
+    flush(): void;
+    /**
+     * Get trajectory metadata
+     */
+    getTrajectory(trajectoryId: string): TrajectoryMetadata | undefined;
+    /**
+     * Get all active trajectories
+     */
+    getActiveTrajectories(): TrajectoryMetadata[];
+}
+/**
+ * Create singleton SONA service instances for different use cases
+ */
+export declare const sonaServices: {
+    realtime: SONAService;
+    batch: SONAService;
+    research: SONAService;
+    edge: SONAService;
+    balanced: SONAService;
+};
+/**
+ * Default SONA service (balanced profile)
+ */
+export declare const sonaService: SONAService;
+/**
+ * Convenience function to create custom SONA service
+ */
+export declare function createSONAService(config?: Partial<SONAConfig>): SONAService;
+/**
+ * Example usage based on vibecast sona.test.js patterns
+ */
+export declare function exampleUsage(): Promise<void>;
+//# sourceMappingURL=sona-service.d.ts.map

package/dist/services/sona-types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * TypeScript interfaces for SONA engine
+ *
+ * Replaces 'any' types with proper interfaces for type safety
+ */
+export interface SONAPattern {
+    id: string;
+    avgQuality: number;
+    similarity: number;
+    context?: string;
+    embedding?: number[];
+    route?: string;
+}
+export interface SONAStats {
+    totalPatterns: number;
+    avgQuality: number;
+    trajectories: number;
+    trajectoryUtilization: number;
+    routes: Record<string, number>;
+    qualityDistribution: {
+        high: number;
+        medium: number;
+        low: number;
+    };
+}
+export interface LearnResult {
+    patternsLearned: number;
+    quality: number;
+    convergence: boolean;
+    epochs: number;
+}
+export interface TrajectoryContext {
+    route?: string;
+    metadata: Record<string, string>;
+}
+/**
+ * SONA Engine Interface
+ *
+ * Core methods for trajectory management and LoRA adaptation
+ */
+export interface SONAEngine {
+    /**
+     * Begin a new trajectory for learning
+     * @param embedding - Initial embedding vector (should be 3072D)
+     * @returns Trajectory ID
+     */
+    beginTrajectory(embedding: number[]): string;
+    /**
+     * Set the route (agent/task name) for a trajectory
+     * @param id - Trajectory ID
+     * @param route - Route name
+     */
+    setTrajectoryRoute(id: string, route: string): void;
+    /**
+     * Add context metadata to a trajectory
+     * @param id - Trajectory ID
+     * @param context - Context string (format: "key:value")
+     */
+    addTrajectoryContext(id: string, context: string): void;
+    /**
+     * Add a step to the trajectory with hidden states and attention
+     * @param id - Trajectory ID
+     * @param hiddenStates - Hidden layer activations
+     * @param attentionWeights - Attention scores
+     * @param quality - Quality score (0-1)
+     */
+    addTrajectoryStep(id: string, hiddenStates: number[], attentionWeights: number[], quality: number): void;
+    /**
+     * End a trajectory and trigger LoRA update
+     * @param id - Trajectory ID
+     * @param finalQuality - Final quality score (0-1)
+     */
+    endTrajectory(id: string, finalQuality: number): void;
+    /**
+     * Find similar patterns using learned LoRA weights
+     * @param queryEmbedding - Query vector
+     * @param k - Number of results
+     * @returns Array of patterns
+     */
+    findPatterns(queryEmbedding: number[], k: number): SONAPattern[];
+    /**
+     * Apply Micro-LoRA adaptation to an embedding
+     * @param embedding - Input embedding
+     * @returns Adapted embedding
+     */
+    applyMicroLora(embedding: number[]): number[];
+    /**
+     * Force a learning cycle to update LoRA weights
+     * @returns Learning result
+     */
+    forceLearn(): LearnResult;
+    /**
+     * Get engine statistics
+     * @returns Statistics object
+     */
+    getStats(): SONAStats;
+}
+/**
+ * Validation utilities
+ */
+export declare class ValidationUtils {
+    /**
+     * Validate embedding dimensions
+     */
+    static validateEmbedding(embedding: number[], expectedDim?: number, name?: string): void;
+    /**
+     * Validate quality score
+     */
+    static validateQuality(quality: number, name?: string): void;
+    /**
+     * Validate hidden states and attention weights
+     */
+    static validateStates(hiddenStates: number[], attention: number[], expectedDim?: number): void;
+    /**
+     * Sanitize file path to prevent traversal attacks
+     */
+    static sanitizePath(inputPath: string, baseDir?: string): string;
+}
+//# sourceMappingURL=sona-types.d.ts.map

package/dist/swarm/index.d.ts

@@ -0,0 +1,51 @@
+export { QuicCoordinator, type SwarmAgent, type SwarmMessage, type SwarmState, type SwarmStats, type QuicCoordinatorConfig } from './quic-coordinator.js';
+export { TransportRouter, type TransportProtocol, type TransportConfig, type TransportStats, type RouteResult } from './transport-router.js';
+import { QuicCoordinator, SwarmAgent } from './quic-coordinator.js';
+import { TransportRouter } from './transport-router.js';
+export interface SwarmInitOptions {
+    swarmId: string;
+    topology: 'mesh' | 'hierarchical' | 'ring' | 'star';
+    transport?: 'quic' | 'http2' | 'auto';
+    maxAgents?: number;
+    quicPort?: number;
+    quicHost?: string;
+    enableFallback?: boolean;
+}
+export interface SwarmInstance {
+    swarmId: string;
+    topology: 'mesh' | 'hierarchical' | 'ring' | 'star';
+    transport: 'quic' | 'http2';
+    coordinator?: QuicCoordinator;
+    router: TransportRouter;
+    registerAgent: (agent: SwarmAgent) => Promise<void>;
+    unregisterAgent: (agentId: string) => Promise<void>;
+    getStats: () => any;
+    shutdown: () => Promise<void>;
+}
+/**
+ * Initialize a multi-agent swarm with QUIC transport
+ *
+ * @example
+ * ```typescript
+ * const swarm = await initSwarm({
+ *   swarmId: 'my-swarm',
+ *   topology: 'mesh',
+ *   transport: 'quic',
+ *   quicPort: 4433
+ * });
+ *
+ * await swarm.registerAgent({
+ *   id: 'agent-1',
+ *   role: 'worker',
+ *   host: 'localhost',
+ *   port: 4434,
+ *   capabilities: ['compute', 'analyze']
+ * });
+ * ```
+ */
+export declare function initSwarm(options: SwarmInitOptions): Promise<SwarmInstance>;
+/**
+ * Check if QUIC transport is available
+ */
+export declare function checkQuicAvailability(): Promise<boolean>;
+//# sourceMappingURL=index.d.ts.map

package/dist/swarm/quic-coordinator.d.ts

@@ -0,0 +1,149 @@
+import { QuicClient, QuicConnectionPool, QuicConnection, QuicStats } from '../transport/quic.js';
+export type SwarmTopology = 'mesh' | 'hierarchical' | 'ring' | 'star';
+export type AgentRole = 'coordinator' | 'worker' | 'aggregator' | 'validator';
+export interface SwarmAgent {
+    id: string;
+    role: AgentRole;
+    host: string;
+    port: number;
+    capabilities: string[];
+    metadata?: Record<string, any>;
+}
+export interface SwarmMessage {
+    id: string;
+    from: string;
+    to: string | string[];
+    type: 'task' | 'result' | 'state' | 'heartbeat' | 'sync';
+    payload: any;
+    timestamp: number;
+    ttl?: number;
+}
+export interface SwarmState {
+    swarmId: string;
+    topology: SwarmTopology;
+    agents: Map<string, SwarmAgent>;
+    connections: Map<string, QuicConnection>;
+    stats: SwarmStats;
+}
+export interface SwarmStats {
+    totalAgents: number;
+    activeAgents: number;
+    totalMessages: number;
+    messagesPerSecond: number;
+    averageLatency: number;
+    quicStats: QuicStats;
+}
+export interface QuicCoordinatorConfig {
+    swarmId: string;
+    topology: SwarmTopology;
+    maxAgents: number;
+    quicClient: QuicClient;
+    connectionPool: QuicConnectionPool;
+    heartbeatInterval?: number;
+    statesSyncInterval?: number;
+    enableCompression?: boolean;
+}
+/**
+ * QuicCoordinator - Manages multi-agent swarm coordination over QUIC
+ *
+ * Features:
+ * - Agent-to-agent communication via QUIC streams
+ * - Topology-aware message routing (mesh, hierarchical, ring, star)
+ * - Connection pooling for efficient resource usage
+ * - Real-time state synchronization
+ * - Per-agent statistics tracking
+ */
+export declare class QuicCoordinator {
+    private config;
+    private state;
+    private messageQueue;
+    private heartbeatTimer?;
+    private syncTimer?;
+    private messageStats;
+    constructor(config: QuicCoordinatorConfig);
+    /**
+     * Start the coordinator (heartbeat and state sync)
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the coordinator
+     */
+    stop(): Promise<void>;
+    /**
+     * Register an agent in the swarm
+     */
+    registerAgent(agent: SwarmAgent): Promise<void>;
+    /**
+     * Unregister an agent from the swarm
+     */
+    unregisterAgent(agentId: string): Promise<void>;
+    /**
+     * Send message to one or more agents
+     */
+    sendMessage(message: SwarmMessage): Promise<void>;
+    /**
+     * Broadcast message to all agents (except sender)
+     */
+    broadcast(message: Omit<SwarmMessage, 'to'>): Promise<void>;
+    /**
+     * Get current swarm state
+     */
+    getState(): Promise<SwarmState>;
+    /**
+     * Get agent statistics
+     */
+    getAgentStats(agentId: string): {
+        sent: number;
+        received: number;
+        avgLatency: number;
+    } | null;
+    /**
+     * Get all agent statistics
+     */
+    getAllAgentStats(): Map<string, {
+        sent: number;
+        received: number;
+        avgLatency: number;
+    }>;
+    /**
+     * Synchronize state across all agents
+     */
+    syncState(): Promise<void>;
+    /**
+     * Establish topology-specific connections
+     */
+    private establishTopologyConnections;
+    /**
+     * Resolve message recipients based on topology
+     */
+    private resolveRecipients;
+    /**
+     * Apply topology-specific routing rules
+     */
+    private applyTopologyRouting;
+    /**
+     * Send message to specific agent
+     */
+    private sendToAgent;
+    /**
+     * Serialize message to bytes
+     */
+    private serializeMessage;
+    /**
+     * Start heartbeat timer
+     */
+    private startHeartbeat;
+    /**
+     * Start state sync timer
+     */
+    private startStateSync;
+    /**
+     * Update message statistics
+     */
+    private updateMessageStats;
+    /**
+     * Calculate current swarm statistics
+     */
+    private calculateStats;
+}
+//# sourceMappingURL=quic-coordinator.d.ts.map

package/dist/swarm/transport-router.d.ts

@@ -0,0 +1,124 @@
+import { QuicCoordinator, SwarmMessage, SwarmAgent } from './quic-coordinator.js';
+export type TransportProtocol = 'quic' | 'http2' | 'auto';
+export interface TransportConfig {
+    protocol: TransportProtocol;
+    enableFallback: boolean;
+    quicConfig?: {
+        host: string;
+        port: number;
+        maxConnections: number;
+        certPath?: string;
+        keyPath?: string;
+    };
+    http2Config?: {
+        host: string;
+        port: number;
+        maxConnections: number;
+        secure: boolean;
+    };
+}
+export interface TransportStats {
+    protocol: 'quic' | 'http2';
+    messagesSent: number;
+    messagesReceived: number;
+    bytesTransferred: number;
+    averageLatency: number;
+    errorRate: number;
+}
+export interface RouteResult {
+    success: boolean;
+    protocol: 'quic' | 'http2';
+    latency: number;
+    error?: string;
+}
+/**
+ * TransportRouter - Intelligent transport layer with automatic protocol selection
+ *
+ * Features:
+ * - Automatic QUIC/HTTP2 protocol selection
+ * - Transparent fallback on failure
+ * - Connection pooling for both protocols
+ * - Per-protocol statistics tracking
+ * - Health checking and availability detection
+ */
+export declare class TransportRouter {
+    private config;
+    private quicClient?;
+    private quicPool?;
+    private quicCoordinator?;
+    private http2Sessions;
+    private currentProtocol;
+    private stats;
+    private healthCheckTimer?;
+    private quicAvailable;
+    constructor(config: TransportConfig);
+    /**
+     * Initialize transport router
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize QUIC transport
+     */
+    private initializeQuic;
+    /**
+     * Initialize HTTP/2 transport
+     */
+    private initializeHttp2;
+    /**
+     * Initialize QUIC coordinator for swarm
+     */
+    initializeSwarm(swarmId: string, topology: 'mesh' | 'hierarchical' | 'ring' | 'star', maxAgents?: number): Promise<QuicCoordinator>;
+    /**
+     * Route message through appropriate transport
+     */
+    route(message: SwarmMessage, target: SwarmAgent): Promise<RouteResult>;
+    /**
+     * Send message via QUIC
+     */
+    private sendViaQuic;
+    /**
+     * Send message via HTTP/2
+     */
+    private sendViaHttp2;
+    /**
+     * Get current transport protocol
+     */
+    getCurrentProtocol(): 'quic' | 'http2';
+    /**
+     * Check if QUIC is available
+     */
+    isQuicAvailable(): boolean;
+    /**
+     * Get transport statistics
+     */
+    getStats(protocol?: 'quic' | 'http2'): TransportStats | Map<'quic' | 'http2', TransportStats>;
+    /**
+     * Get QUIC coordinator (if initialized)
+     */
+    getCoordinator(): QuicCoordinator | undefined;
+    /**
+     * Shutdown transport router
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Start health checks for protocol availability
+     */
+    private startHealthChecks;
+    /**
+     * Check QUIC health
+     */
+    private checkQuicHealth;
+    /**
+     * Update transport statistics
+     */
+    private updateStats;
+    /**
+     * Serialize message to bytes
+     */
+    private serializeMessage;
+    /**
+     * Estimate message size in bytes
+     */
+    private estimateMessageSize;
+}
+//# sourceMappingURL=transport-router.d.ts.map

package/dist/transport/index.d.ts

@@ -0,0 +1,2 @@
+export * from './quic.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/transport/quic-handshake.d.ts

@@ -0,0 +1,66 @@
+export declare enum HandshakeState {
+    Initial = "initial",
+    Handshaking = "handshaking",
+    Established = "established",
+    Failed = "failed",
+    Closed = "closed"
+}
+export interface QuicHandshakeContext {
+    connectionId: string;
+    state: HandshakeState;
+    remoteAddr: string;
+    startTime: number;
+    wasmClient: any;
+    createMessage: any;
+    onEstablished?: () => void;
+    onFailed?: (error: Error) => void;
+}
+/**
+ * QUIC Handshake Manager
+ * Implements connection establishment protocol using WASM sendMessage/recvMessage
+ */
+export declare class QuicHandshakeManager {
+    private contexts;
+    constructor();
+    /**
+     * Initiate QUIC handshake for a new connection
+     */
+    initiateHandshake(connectionId: string, remoteAddr: string, wasmClient: any, createMessage: any): Promise<boolean>;
+    /**
+     * Send QUIC Initial packet
+     */
+    private sendInitialPacket;
+    /**
+     * Wait for Server Hello response
+     */
+    private waitForServerHello;
+    /**
+     * Send Handshake Complete packet
+     */
+    private sendHandshakeComplete;
+    /**
+     * Create QUIC Initial packet payload
+     */
+    private createInitialPayload;
+    /**
+     * Create Handshake Complete payload
+     */
+    private createHandshakeCompletePayload;
+    /**
+     * Get handshake state for connection
+     */
+    getHandshakeState(connectionId: string): HandshakeState;
+    /**
+     * Check if connection is established
+     */
+    isEstablished(connectionId: string): boolean;
+    /**
+     * Close handshake context
+     */
+    closeHandshake(connectionId: string): void;
+    /**
+     * Get all active handshakes
+     */
+    getActiveHandshakes(): string[];
+}
+//# sourceMappingURL=quic-handshake.d.ts.map