npm - agentic-flow - Versions diffs - 1.9.0 → 1.9.2 - Mend

agentic-flow 1.9.0 → 1.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1223) hide show

package/docs/features/quic/QUIC-INTEGRATION.md DELETED Viewed

@@ -1,502 +0,0 @@
-# QUIC Transport Integration Guide
-This guide covers the QUIC/HTTP3 transport layer integration for agentic-flow, providing faster and more reliable network performance.
-## Overview
-QUIC (Quick UDP Internet Connections) is a modern transport protocol developed by Google that provides:
-- **Faster Connection Establishment**: 0-RTT and 1-RTT handshakes vs 2-RTT for TCP+TLS
-- **Improved Multiplexing**: True stream independence without head-of-line blocking
-- **Better Loss Recovery**: Per-stream congestion control
-- **Connection Migration**: Seamless transition between networks
-- **Built-in Encryption**: TLS 1.3 integrated into the protocol
-## Features
-- ✅ **TypeScript QUIC Client** - Connection pooling and stream multiplexing
-- ✅ **TypeScript QUIC Server** - High-performance server implementation
-- ✅ **HTTP/3 Support** - Automatic HTTP/3 over QUIC
-- ✅ **Automatic Fallback** - Graceful fallback to HTTP/2 when needed
-- ✅ **Feature Flag** - Easy enable/disable via environment variable
-- ✅ **Health Monitoring** - Built-in health checks and metrics
-- ✅ **Configuration Schema** - Comprehensive configuration options
-## Quick Start
-### 1. Enable QUIC Transport
-Set the environment variable to enable QUIC:
-```bash
-export AGENTIC_FLOW_ENABLE_QUIC=true
-```
-### 2. Configure TLS Certificates
-QUIC requires TLS 1.3 certificates:
-```bash
-# Generate self-signed certificates for development
-mkdir -p certs
-openssl req -x509 -newkey rsa:4096 -nodes \
-  -keyout certs/key.pem \
-  -out certs/cert.pem \
-  -days 365 \
-  -subj "/CN=localhost"
-```
-### 3. Start Proxy with QUIC
-```bash
-# Using environment variables
-export OPENROUTER_API_KEY=your_key_here
-export AGENTIC_FLOW_ENABLE_QUIC=true
-export QUIC_PORT=4433
-npm run proxy:quic
-```
-Or programmatically:
-```typescript
-import { createQuicProxy } from 'agentic-flow/proxy/quic-proxy';
-const proxy = createQuicProxy({
-  openrouterApiKey: process.env.OPENROUTER_API_KEY,
-  transport: 'auto', // 'quic' | 'http2' | 'auto'
-  enableQuic: true,
-  quic: {
-    port: 4433,
-    certPath: './certs/cert.pem',
-    keyPath: './certs/key.pem',
-    maxConnections: 100,
-    maxConcurrentStreams: 100
-  },
-  fallbackToHttp2: true
-});
-proxy.start(3000);
-```
-## Configuration Options
-### Environment Variables
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `AGENTIC_FLOW_ENABLE_QUIC` | `false` | Enable QUIC transport |
-| `QUIC_PORT` | `4433` | QUIC server/client port |
-| `QUIC_HOST` | `0.0.0.0` | QUIC bind host |
-| `QUIC_SERVER_HOST` | `localhost` | QUIC server hostname |
-| `QUIC_SERVER_PORT` | `4433` | QUIC server port |
-| `QUIC_CERT_PATH` | `./certs/cert.pem` | TLS certificate path |
-| `QUIC_KEY_PATH` | `./certs/key.pem` | TLS private key path |
-| `QUIC_MAX_CONNECTIONS` | `100` | Max connection pool size |
-| `QUIC_MAX_STREAMS` | `100` | Max concurrent streams |
-| `QUIC_VERIFY_PEER` | `true` | Verify peer certificates |
-### TypeScript Configuration
-```typescript
-import { QuicConfig } from 'agentic-flow/transport/quic';
-import { loadQuicConfig } from 'agentic-flow/config/quic';
-// Load configuration with defaults
-const config = loadQuicConfig({
-  enabled: true,
-  port: 4433,
-  maxConnections: 100,
-  maxConcurrentStreams: 100,
-  connectionTimeout: 30000,
-  idleTimeout: 60000,
-  streamTimeout: 30000,
-  enableEarlyData: true,
-  fallbackToHttp2: true
-});
-```
-## Usage Examples
-### 1. Basic QUIC Client
-```typescript
-import { QuicClient } from 'agentic-flow/transport/quic';
-const client = new QuicClient({
-  serverHost: 'api.example.com',
-  serverPort: 4433,
-  verifyPeer: true
-});
-await client.initialize();
-// Connect to server
-const connection = await client.connect();
-// Create bidirectional stream
-const stream = await client.createStream(connection.id);
-// Send data
-const request = new TextEncoder().encode('Hello QUIC');
-await stream.send(request);
-// Receive response
-const response = await stream.receive();
-console.log(new TextDecoder().decode(response));
-// Close stream
-await stream.close();
-// Cleanup
-await client.shutdown();
-```
-### 2. QUIC Server
-```typescript
-import { QuicServer } from 'agentic-flow/transport/quic';
-const server = new QuicServer({
-  host: '0.0.0.0',
-  port: 4433,
-  certPath: './certs/cert.pem',
-  keyPath: './certs/key.pem',
-  maxConnections: 1000
-});
-await server.initialize();
-await server.listen();
-console.log('QUIC server listening on port 4433');
-// Graceful shutdown
-process.on('SIGTERM', async () => {
-  await server.stop();
-});
-```
-### 3. Connection Pool
-```typescript
-import { QuicClient, QuicConnectionPool } from 'agentic-flow/transport/quic';
-const client = new QuicClient();
-await client.initialize();
-const pool = new QuicConnectionPool(client, 20);
-// Get or create connection
-const conn = await pool.getConnection('api.example.com', 4433);
-// Reuse existing connection
-const conn2 = await pool.getConnection('api.example.com', 4433);
-console.log(conn.id === conn2.id); // true
-// Cleanup
-await pool.clear();
-```
-### 4. HTTP/3 Requests
-```typescript
-import { QuicClient } from 'agentic-flow/transport/quic';
-const client = new QuicClient();
-await client.initialize();
-const connection = await client.connect('api.example.com', 443);
-const response = await client.sendRequest(
-  connection.id,
-  'POST',
-  '/v1/chat/completions',
-  {
-    'Content-Type': 'application/json',
-    'Authorization': 'Bearer your_token'
-  },
-  new TextEncoder().encode(JSON.stringify({
-    model: 'gpt-4',
-    messages: [{ role: 'user', content: 'Hello' }]
-  }))
-);
-console.log('Status:', response.status);
-console.log('Body:', new TextDecoder().decode(response.body));
-```
-## Health Checks
-### Check QUIC Availability
-```bash
-# General health endpoint (includes QUIC status)
-curl http://localhost:8080/health
-# QUIC-specific health endpoint
-curl http://localhost:8080/health/quic
-```
-Response:
-```json
-{
-  "enabled": true,
-  "available": true,
-  "config": {
-    "host": "0.0.0.0",
-    "port": 4433,
-    "maxConnections": 100,
-    "maxStreams": 100
-  }
-}
-```
-### Programmatic Health Check
-```typescript
-import { checkQuicAvailability } from 'agentic-flow/config/quic';
-const status = await checkQuicAvailability();
-console.log('QUIC available:', status.available);
-if (!status.available) {
-  console.log('Reason:', status.reason);
-}
-```
-## Performance Metrics
-Get real-time QUIC statistics:
-```typescript
-import { QuicClient } from 'agentic-flow/transport/quic';
-const client = new QuicClient();
-await client.initialize();
-const stats = client.getStats();
-console.log({
-  activeConnections: stats.activeConnections,
-  activeStreams: stats.activeStreams,
-  bytesReceived: stats.bytesReceived,
-  bytesSent: stats.bytesSent,
-  packetsLost: stats.packetsLost,
-  rttMs: stats.rttMs
-});
-```
-## Transport Selection
-The proxy supports three transport modes:
-### 1. Auto Mode (Recommended)
-Automatically selects QUIC if available, falls back to HTTP/2:
-```typescript
-const proxy = createQuicProxy({
-  openrouterApiKey: 'your_key',
-  transport: 'auto',
-  enableQuic: true,
-  fallbackToHttp2: true
-});
-```
-### 2. QUIC Only
-Forces QUIC transport, fails if unavailable:
-```typescript
-const proxy = createQuicProxy({
-  openrouterApiKey: 'your_key',
-  transport: 'quic',
-  enableQuic: true,
-  fallbackToHttp2: false
-});
-```
-### 3. HTTP/2 Only
-Disables QUIC entirely:
-```typescript
-const proxy = createQuicProxy({
-  openrouterApiKey: 'your_key',
-  transport: 'http2',
-  enableQuic: false
-});
-```
-## Troubleshooting
-### Issue: QUIC Connection Fails
-**Symptoms**: Connections timeout or fail to establish
-**Solutions**:
-1. Verify UDP port 4433 is open:
-   ```bash
-   sudo netstat -tulpn | grep 4433
-   ```
-2. Check firewall rules:
-   ```bash
-   sudo ufw allow 4433/udp
-   ```
-3. Verify certificates:
-   ```bash
-   openssl x509 -in certs/cert.pem -text -noout
-   ```
-### Issue: Fallback to HTTP/2
-**Symptoms**: All requests use HTTP/2 instead of QUIC
-**Solutions**:
-1. Check QUIC is enabled:
-   ```bash
-   echo $AGENTIC_FLOW_ENABLE_QUIC
-   ```
-2. Verify WASM module is loaded:
-   ```typescript
-   import { checkQuicAvailability } from 'agentic-flow/config/quic';
-   const status = await checkQuicAvailability();
-   console.log(status);
-   ```
-3. Check logs for initialization errors:
-   ```bash
-   grep "QUIC" logs/agentic-flow.log
-   ```
-### Issue: Certificate Errors
-**Symptoms**: TLS handshake failures
-**Solutions**:
-1. For development, disable peer verification:
-   ```bash
-   export QUIC_VERIFY_PEER=false
-   ```
-2. For production, use proper certificates:
-   ```bash
-   # Use Let's Encrypt
-   certbot certonly --standalone -d your-domain.com
-   export QUIC_CERT_PATH=/etc/letsencrypt/live/your-domain.com/fullchain.pem
-   export QUIC_KEY_PATH=/etc/letsencrypt/live/your-domain.com/privkey.pem
-   ```
-## Performance Benchmarks
-Comparison of QUIC vs HTTP/2 for API requests:
-| Metric | HTTP/2 | QUIC | Improvement |
-|--------|--------|------|-------------|
-| Connection Time | 50-100ms | 0-30ms | 2-3x faster |
-| First Byte Time | 100-200ms | 50-100ms | 2x faster |
-| Request Latency | 200-400ms | 100-250ms | 1.5-2x faster |
-| Packet Loss Tolerance | Poor | Excellent | Better recovery |
-| Network Mobility | No | Yes | Seamless handoff |
-## Best Practices
-### 1. Use Connection Pooling
-```typescript
-// Good: Reuse connections
-const pool = new QuicConnectionPool(client, 20);
-const conn = await pool.getConnection(host, port);
-// Bad: Create new connections every time
-const conn = await client.connect(host, port);
-```
-### 2. Handle Errors Gracefully
-```typescript
-try {
-  const response = await client.sendRequest(...);
-} catch (error) {
-  if (error.code === 'QUIC_TIMEOUT') {
-    // Fallback to HTTP/2
-    return await fetchViaHttp2();
-  }
-  throw error;
-}
-```
-### 3. Monitor Performance
-```typescript
-setInterval(() => {
-  const stats = client.getStats();
-  if (stats.packetsLost > 100) {
-    logger.warn('High packet loss detected', { stats });
-  }
-}, 60000);
-```
-### 4. Configure Timeouts
-```typescript
-const config = loadQuicConfig({
-  connectionTimeout: 30000, // 30 seconds
-  idleTimeout: 120000,      // 2 minutes
-  streamTimeout: 30000      // 30 seconds
-});
-```
-## Integration with Router
-Add QUIC transport to router configuration:
-```json
-{
-  "providers": {
-    "openrouter": {
-      "transport": {
-        "protocol": "quic",
-        "fallback": "http2",
-        "config": {
-          "port": 4433,
-          "maxConnections": 100
-        }
-      }
-    }
-  }
-}
-```
-## Security Considerations
-1. **Always use TLS**: QUIC includes TLS 1.3 by default
-2. **Verify Peer Certificates**: Enable in production
-3. **Update Certificates Regularly**: Use automated renewal
-4. **Monitor for Vulnerabilities**: Keep WASM module updated
-5. **Rate Limiting**: Implement at application layer
-## Future Enhancements
-- [ ] WASM module compilation and integration
-- [ ] HTTP/3 QPACK header compression
-- [ ] 0-RTT connection resumption
-- [ ] Connection migration support
-- [ ] Advanced congestion control (BBR)
-- [ ] QUIC load balancing
-- [ ] Performance profiling tools
-## References
-- [QUIC Protocol RFC 9000](https://www.rfc-editor.org/rfc/rfc9000.html)
-- [HTTP/3 RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html)
-- [QPACK RFC 9204](https://www.rfc-editor.org/rfc/rfc9204.html)
-- [TLS 1.3 RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)
-## Support
-For issues or questions:
-- GitHub Issues: https://github.com/ruvnet/agentic-flow/issues
-- Documentation: https://github.com/ruvnet/agentic-flow/docs

package/docs/features/quic/QUIC-README.md DELETED Viewed

@@ -1,226 +0,0 @@
-# QUIC Transport for Agentic Flow
-High-performance QUIC/HTTP3 transport layer for faster and more reliable agent communication.
-## Features
-- 🚀 **2-3x Faster Connections** - 0-RTT and 1-RTT handshakes vs TCP's 2-RTT
-- 🔄 **Stream Multiplexing** - True independence without head-of-line blocking
-- 📦 **Connection Pooling** - Efficient connection reuse
-- 🔌 **Auto Fallback** - Graceful HTTP/2 fallback when needed
-- 🏥 **Health Monitoring** - Built-in health checks and metrics
-- 🔐 **TLS 1.3 Built-in** - Encryption integrated into protocol
-## Quick Start
-```bash
-# Enable QUIC transport
-export AGENTIC_FLOW_ENABLE_QUIC=true
-# Generate certificates (development)
-mkdir -p certs
-openssl req -x509 -newkey rsa:4096 -nodes \
-  -keyout certs/key.pem \
-  -out certs/cert.pem \
-  -days 365 \
-  -subj "/CN=localhost"
-# Start proxy with QUIC
-npm run proxy:quic
-```
-## Configuration
-### Environment Variables
-```bash
-export AGENTIC_FLOW_ENABLE_QUIC=true
-export QUIC_PORT=4433
-export QUIC_HOST=0.0.0.0
-export QUIC_CERT_PATH=./certs/cert.pem
-export QUIC_KEY_PATH=./certs/key.pem
-export QUIC_MAX_CONNECTIONS=100
-export QUIC_MAX_STREAMS=100
-```
-### Programmatic
-```typescript
-import { createQuicProxy } from 'agentic-flow/proxy/quic-proxy';
-const proxy = createQuicProxy({
-  openrouterApiKey: process.env.OPENROUTER_API_KEY,
-  transport: 'auto', // 'quic' | 'http2' | 'auto'
-  enableQuic: true,
-  quic: {
-    port: 4433,
-    maxConnections: 100,
-    maxConcurrentStreams: 100
-  },
-  fallbackToHttp2: true
-});
-proxy.start(3000);
-```
-## Usage Examples
-### Client
-```typescript
-import { QuicClient } from 'agentic-flow/transport/quic';
-const client = new QuicClient({
-  serverHost: 'api.example.com',
-  serverPort: 4433
-});
-await client.initialize();
-const connection = await client.connect();
-const stream = await client.createStream(connection.id);
-await stream.send(new TextEncoder().encode('Hello'));
-const response = await stream.receive();
-await stream.close();
-await client.shutdown();
-```
-### Server
-```typescript
-import { QuicServer } from 'agentic-flow/transport/quic';
-const server = new QuicServer({
-  host: '0.0.0.0',
-  port: 4433,
-  certPath: './certs/cert.pem',
-  keyPath: './certs/key.pem'
-});
-await server.initialize();
-await server.listen();
-```
-### Connection Pool
-```typescript
-import { QuicClient, QuicConnectionPool } from 'agentic-flow/transport/quic';
-const client = new QuicClient();
-await client.initialize();
-const pool = new QuicConnectionPool(client, 20);
-const conn = await pool.getConnection('api.example.com', 4433);
-// Automatically reuses existing connections
-const conn2 = await pool.getConnection('api.example.com', 4433);
-console.log(conn.id === conn2.id); // true
-```
-## Health Checks
-```bash
-# Check overall health (includes QUIC)
-curl http://localhost:8080/health
-# QUIC-specific health
-curl http://localhost:8080/health/quic
-```
-## Performance
-| Metric | HTTP/2 | QUIC | Improvement |
-|--------|--------|------|-------------|
-| Connection Time | 50-100ms | 0-30ms | 2-3x |
-| First Byte | 100-200ms | 50-100ms | 2x |
-| Latency | 200-400ms | 100-250ms | 1.5-2x |
-## Testing
-```bash
-# Run QUIC integration tests
-npm run test:quic
-# Test with development proxy
-npm run proxy:quic:dev
-```
-## Troubleshooting
-### QUIC Not Available
-Check availability:
-```typescript
-import { checkQuicAvailability } from 'agentic-flow/config/quic';
-const status = await checkQuicAvailability();
-console.log(status);
-```
-### Connection Timeouts
-1. Verify UDP port 4433 is open:
-   ```bash
-   sudo netstat -tulpn | grep 4433
-   ```
-2. Check firewall:
-   ```bash
-   sudo ufw allow 4433/udp
-   ```
-### Certificate Issues
-For development:
-```bash
-export QUIC_VERIFY_PEER=false
-```
-For production, use proper certificates from Let's Encrypt.
-## Documentation
-- [Full Integration Guide](./QUIC-INTEGRATION.md)
-- [API Reference](./API.md)
-- [Configuration Schema](./CONFIG.md)
-## Architecture
-```
-┌─────────────────┐
-│  QUIC Client    │
-│  - Connection   │
-│    Pool         │
-│  - Stream Mux   │
-└────────┬────────┘
-         │
-         │ UDP/QUIC
-         │
-┌────────▼────────┐
-│  QUIC Server    │
-│  - TLS 1.3      │
-│  - HTTP/3       │
-└─────────────────┘
-```
-## Requirements
-- Node.js >= 18.0.0
-- UDP port 4433 accessible
-- TLS 1.3 certificates
-## Roadmap
-- [ ] WASM module integration
-- [ ] HTTP/3 QPACK compression
-- [ ] 0-RTT resumption
-- [ ] Connection migration
-- [ ] BBR congestion control
-## References
-- [QUIC RFC 9000](https://www.rfc-editor.org/rfc/rfc9000.html)
-- [HTTP/3 RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html)
-- [TLS 1.3 RFC 8446](https://www.rfc-editor.org/rfc/rfc8446.html)