agent-relay 1.3.0 → 1.3.2

package/dist/daemon/sync-queue.js

@@ -0,0 +1,361 @@
+/**
+ * Optimized Cloud Sync Queue
+ *
+ * Handles batched, compressed, resilient message syncing to cloud.
+ * Features:
+ * - Adaptive batching (size/time/bytes triggers)
+ * - Gzip compression for payloads over threshold
+ * - Disk spillover for offline resilience
+ * - Retry with exponential backoff
+ * - Startup reconciliation
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { gzip } from 'node:zlib';
+import { promisify } from 'node:util';
+import { generateId } from '../utils/id-generator.js';
+import { createLogger } from '../utils/logger.js';
+const gzipAsync = promisify(gzip);
+const log = createLogger('sync-queue');
+export const DEFAULT_SYNC_QUEUE_CONFIG = {
+    cloudUrl: 'https://agent-relay.com',
+    apiKey: '',
+    batchSize: 100,
+    batchDelayMs: 200,
+    maxBatchBytes: 512 * 1024, // 512KB
+    compressionThreshold: 1024, // 1KB
+    spillDir: path.join(os.tmpdir(), 'agent-relay-sync'),
+    maxSpillFiles: 100,
+    maxRetries: 3,
+    retryDelayMs: 1000,
+    verbose: false,
+};
+export class SyncQueue {
+    config;
+    queue = [];
+    queueBytes = 0;
+    flushTimer;
+    flushing = false;
+    flushPromise;
+    // Stats
+    stats = {
+        queuedMessages: 0,
+        queuedBytes: 0,
+        totalSynced: 0,
+        totalFailed: 0,
+        totalCompressed: 0,
+        totalBytesTransferred: 0,
+        spilledFiles: 0,
+    };
+    constructor(config) {
+        this.config = { ...DEFAULT_SYNC_QUEUE_CONFIG, ...config };
+    }
+    /**
+     * Queue a message for sync to cloud.
+     * May trigger an immediate flush if thresholds are exceeded.
+     */
+    async enqueue(message) {
+        // Wait for any in-progress flush
+        if (this.flushPromise) {
+            await this.flushPromise;
+        }
+        const msgJson = JSON.stringify(message);
+        const sizeBytes = Buffer.byteLength(msgJson, 'utf-8');
+        this.queue.push({ message, sizeBytes });
+        this.queueBytes += sizeBytes;
+        this.stats.queuedMessages = this.queue.length;
+        this.stats.queuedBytes = this.queueBytes;
+        // Check flush triggers
+        const shouldFlush = this.queue.length >= this.config.batchSize ||
+            this.queueBytes >= this.config.maxBatchBytes;
+        if (shouldFlush) {
+            await this.flush();
+        }
+        else if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => {
+                this.flush().catch((err) => {
+                    log.error('Timer flush failed', { error: String(err) });
+                });
+            }, this.config.batchDelayMs);
+        }
+    }
+    /**
+     * Enqueue multiple messages at once.
+     */
+    async enqueueBatch(messages) {
+        for (const msg of messages) {
+            await this.enqueue(msg);
+        }
+    }
+    /**
+     * Flush all queued messages to cloud.
+     */
+    async flush() {
+        // Clear timer
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        // Skip if empty or already flushing
+        if (this.queue.length === 0 || this.flushing) {
+            return { synced: 0, duplicates: 0, failed: 0, compressed: false, bytesTransferred: 0 };
+        }
+        this.flushing = true;
+        // Take current batch
+        const batch = this.queue;
+        const batchBytes = this.queueBytes;
+        this.queue = [];
+        this.queueBytes = 0;
+        this.stats.queuedMessages = 0;
+        this.stats.queuedBytes = 0;
+        this.flushPromise = this.syncBatch(batch, batchBytes);
+        try {
+            const result = await this.flushPromise;
+            return result;
+        }
+        finally {
+            this.flushing = false;
+            this.flushPromise = undefined;
+        }
+    }
+    /**
+     * Sync a batch of messages to cloud with retry and spillover.
+     */
+    async syncBatch(batch, batchBytes) {
+        const messages = batch.map((q) => q.message);
+        let lastError = null;
+        for (let attempt = 0; attempt < this.config.maxRetries; attempt++) {
+            try {
+                const result = await this.sendToCloud(messages, batchBytes);
+                this.stats.totalSynced += result.synced;
+                this.stats.totalBytesTransferred += result.bytesTransferred;
+                if (result.compressed) {
+                    this.stats.totalCompressed++;
+                }
+                this.stats.lastSyncAt = Date.now();
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                this.stats.lastError = lastError.message;
+                if (attempt < this.config.maxRetries - 1) {
+                    // Exponential backoff
+                    const delay = this.config.retryDelayMs * Math.pow(2, attempt);
+                    if (this.config.verbose) {
+                        log.warn(`Sync attempt ${attempt + 1} failed, retrying in ${delay}ms`, {
+                            error: lastError.message,
+                        });
+                    }
+                    await this.sleep(delay);
+                }
+            }
+        }
+        // All retries failed - spill to disk
+        log.error('Sync failed after retries, spilling to disk', {
+            count: messages.length,
+            error: lastError?.message,
+        });
+        await this.spillToDisk(messages);
+        this.stats.totalFailed += messages.length;
+        return {
+            synced: 0,
+            duplicates: 0,
+            failed: messages.length,
+            compressed: false,
+            bytesTransferred: 0,
+        };
+    }
+    /**
+     * Send messages to cloud API with optional compression.
+     */
+    async sendToCloud(messages, _estimatedBytes) {
+        // Transform to API format
+        const syncPayload = {
+            messages: messages.map((msg) => ({
+                id: msg.id,
+                ts: msg.ts,
+                from: msg.from,
+                to: msg.to,
+                body: msg.body,
+                kind: msg.kind,
+                topic: msg.topic,
+                thread: msg.thread,
+                is_broadcast: msg.is_broadcast,
+                is_urgent: msg.is_urgent,
+                data: msg.data,
+                payload_meta: msg.payloadMeta,
+            })),
+        };
+        const payloadJson = JSON.stringify(syncPayload);
+        const payloadBytes = Buffer.byteLength(payloadJson, 'utf-8');
+        // Determine if we should compress
+        const shouldCompress = payloadBytes > this.config.compressionThreshold;
+        let body;
+        let contentEncoding;
+        if (shouldCompress) {
+            body = await gzipAsync(Buffer.from(payloadJson));
+            contentEncoding = 'gzip';
+            if (this.config.verbose) {
+                const ratio = ((1 - body.length / payloadBytes) * 100).toFixed(1);
+                log.info(`Compressed ${payloadBytes} → ${body.length} bytes (${ratio}% reduction)`);
+            }
+        }
+        else {
+            body = payloadJson;
+        }
+        const headers = {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+        if (contentEncoding) {
+            headers['Content-Encoding'] = contentEncoding;
+        }
+        const response = await fetch(`${this.config.cloudUrl}/api/daemons/messages/sync`, {
+            method: 'POST',
+            headers,
+            body,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Sync failed: ${response.status} - ${errorText}`);
+        }
+        const result = (await response.json());
+        return {
+            synced: result.synced,
+            duplicates: result.duplicates,
+            failed: 0,
+            compressed: shouldCompress,
+            bytesTransferred: typeof body === 'string' ? Buffer.byteLength(body) : body.length,
+        };
+    }
+    /**
+     * Spill failed batch to disk for later recovery.
+     */
+    async spillToDisk(messages) {
+        try {
+            await fs.mkdir(this.config.spillDir, { recursive: true });
+            const filename = `spill-${Date.now()}-${generateId().replace(/-/g, '')}.json`;
+            const filepath = path.join(this.config.spillDir, filename);
+            await fs.writeFile(filepath, JSON.stringify(messages));
+            this.stats.spilledFiles++;
+            if (this.config.verbose) {
+                log.info(`Spilled ${messages.length} messages to ${filename}`);
+            }
+            // Cleanup old spill files
+            await this.cleanupSpillFiles();
+        }
+        catch (err) {
+            log.error('Failed to spill to disk', { error: String(err) });
+        }
+    }
+    /**
+     * Recover and sync messages from spill files.
+     * Call this on startup to resume failed syncs.
+     */
+    async recoverSpilledMessages() {
+        let recovered = 0;
+        let failed = 0;
+        try {
+            const files = await fs.readdir(this.config.spillDir);
+            const spillFiles = files.filter((f) => f.startsWith('spill-')).sort();
+            for (const file of spillFiles) {
+                const filepath = path.join(this.config.spillDir, file);
+                try {
+                    const content = await fs.readFile(filepath, 'utf-8');
+                    const messages = JSON.parse(content);
+                    // Try to sync
+                    const result = await this.sendToCloud(messages, Buffer.byteLength(content, 'utf-8'));
+                    if (result.synced > 0 || result.duplicates > 0) {
+                        // Success - remove spill file
+                        await fs.unlink(filepath);
+                        recovered += messages.length;
+                        this.stats.spilledFiles = Math.max(0, this.stats.spilledFiles - 1);
+                        if (this.config.verbose) {
+                            log.info(`Recovered ${messages.length} messages from ${file}`);
+                        }
+                    }
+                    else {
+                        failed += messages.length;
+                    }
+                }
+                catch (err) {
+                    log.warn(`Failed to recover ${file}`, { error: String(err) });
+                    failed++;
+                }
+            }
+        }
+        catch (err) {
+            // Directory doesn't exist or other error
+            if (err.code !== 'ENOENT') {
+                log.error('Failed to scan spill directory', { error: String(err) });
+            }
+        }
+        if (recovered > 0) {
+            log.info(`Recovered ${recovered} messages from spill files`);
+        }
+        return { recovered, failed };
+    }
+    /**
+     * Cleanup old spill files beyond the limit.
+     */
+    async cleanupSpillFiles() {
+        try {
+            const files = await fs.readdir(this.config.spillDir);
+            const spillFiles = files.filter((f) => f.startsWith('spill-')).sort();
+            if (spillFiles.length > this.config.maxSpillFiles) {
+                const toDelete = spillFiles.slice(0, spillFiles.length - this.config.maxSpillFiles);
+                for (const file of toDelete) {
+                    await fs.unlink(path.join(this.config.spillDir, file)).catch(() => { });
+                }
+                if (this.config.verbose) {
+                    log.info(`Cleaned up ${toDelete.length} old spill files`);
+                }
+            }
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+    /**
+     * Get sync queue statistics.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset statistics (for testing or periodic reporting).
+     */
+    resetStats() {
+        this.stats = {
+            queuedMessages: this.queue.length,
+            queuedBytes: this.queueBytes,
+            totalSynced: 0,
+            totalFailed: 0,
+            totalCompressed: 0,
+            totalBytesTransferred: 0,
+            spilledFiles: this.stats.spilledFiles, // Preserve spill count
+        };
+    }
+    /**
+     * Gracefully close the queue, flushing any pending messages.
+     */
+    async close() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        // Wait for any in-progress flush
+        if (this.flushPromise) {
+            await this.flushPromise;
+        }
+        // Flush remaining
+        if (this.queue.length > 0) {
+            await this.flush();
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=sync-queue.js.map

package/dist/health-worker-manager.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Health Worker Manager
+ *
+ * Manages the health check worker thread, sending periodic stats updates
+ * and handling worker lifecycle.
+ */
+export interface HealthWorkerConfig {
+    /** Port for health check server (default: main port + 1) */
+    port: number;
+    /** Interval for sending stats updates (default: 5000ms) */
+    statsInterval?: number;
+}
+export interface HealthStatsProvider {
+    getUptime: () => number;
+    getMemoryMB: () => number;
+    getRelayConnected: () => boolean;
+    getAgentCount: () => number;
+    getStatus: () => 'healthy' | 'busy' | 'degraded';
+}
+export declare class HealthWorkerManager {
+    private worker;
+    private statsInterval;
+    private config;
+    private statsProvider;
+    private ready;
+    constructor(config: HealthWorkerConfig, statsProvider: HealthStatsProvider);
+    /**
+     * Start the health worker thread
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the health worker thread
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if worker is ready
+     */
+    isReady(): boolean;
+    /**
+     * Get the port the health worker is listening on
+     */
+    getPort(): number;
+    /**
+     * Start periodic stats updates to worker
+     */
+    private startStatsUpdates;
+    /**
+     * Stop stats updates
+     */
+    private stopStatsUpdates;
+    /**
+     * Send current stats to worker
+     */
+    private sendStats;
+}
+/** Default health port offset from main port */
+export declare const HEALTH_PORT_OFFSET = 1;
+/**
+ * Calculate health port from main port
+ */
+export declare function getHealthPort(mainPort: number): number;
+//# sourceMappingURL=health-worker-manager.d.ts.map

package/dist/health-worker-manager.js

@@ -0,0 +1,144 @@
+/**
+ * Health Worker Manager
+ *
+ * Manages the health check worker thread, sending periodic stats updates
+ * and handling worker lifecycle.
+ */
+import { Worker } from 'node:worker_threads';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export class HealthWorkerManager {
+    worker = null;
+    statsInterval = null;
+    config;
+    statsProvider;
+    ready = false;
+    constructor(config, statsProvider) {
+        this.config = {
+            statsInterval: 5000,
+            ...config,
+        };
+        this.statsProvider = statsProvider;
+    }
+    /**
+     * Start the health worker thread
+     */
+    async start() {
+        if (this.worker) {
+            console.warn('[health-manager] Worker already running');
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            // Worker script path - handle both dev (src) and prod (dist)
+            const workerPath = path.join(__dirname, 'health-worker.js');
+            this.worker = new Worker(workerPath, {
+                workerData: { port: this.config.port },
+            });
+            this.worker.on('message', (msg) => {
+                if (msg.type === 'ready') {
+                    this.ready = true;
+                    console.log(`[health-manager] Worker ready on port ${msg.port}`);
+                    this.startStatsUpdates();
+                    resolve();
+                }
+                else if (msg.type === 'error') {
+                    console.error('[health-manager] Worker error:', msg.error);
+                }
+            });
+            this.worker.on('error', (err) => {
+                console.error('[health-manager] Worker thread error:', err);
+                if (!this.ready) {
+                    reject(err);
+                }
+            });
+            this.worker.on('exit', (code) => {
+                console.log(`[health-manager] Worker exited with code ${code}`);
+                this.ready = false;
+                this.worker = null;
+                this.stopStatsUpdates();
+            });
+            // Timeout for worker startup
+            setTimeout(() => {
+                if (!this.ready) {
+                    reject(new Error('Health worker startup timeout'));
+                }
+            }, 10000);
+        });
+    }
+    /**
+     * Stop the health worker thread
+     */
+    async stop() {
+        this.stopStatsUpdates();
+        if (this.worker) {
+            await this.worker.terminate();
+            this.worker = null;
+            this.ready = false;
+        }
+    }
+    /**
+     * Check if worker is ready
+     */
+    isReady() {
+        return this.ready;
+    }
+    /**
+     * Get the port the health worker is listening on
+     */
+    getPort() {
+        return this.config.port;
+    }
+    /**
+     * Start periodic stats updates to worker
+     */
+    startStatsUpdates() {
+        if (this.statsInterval)
+            return;
+        // Send initial stats
+        this.sendStats();
+        // Send periodic updates
+        this.statsInterval = setInterval(() => {
+            this.sendStats();
+        }, this.config.statsInterval);
+    }
+    /**
+     * Stop stats updates
+     */
+    stopStatsUpdates() {
+        if (this.statsInterval) {
+            clearInterval(this.statsInterval);
+            this.statsInterval = null;
+        }
+    }
+    /**
+     * Send current stats to worker
+     */
+    sendStats() {
+        if (!this.worker || !this.ready)
+            return;
+        try {
+            const stats = {
+                uptime: this.statsProvider.getUptime(),
+                memoryMB: this.statsProvider.getMemoryMB(),
+                relayConnected: this.statsProvider.getRelayConnected(),
+                agentCount: this.statsProvider.getAgentCount(),
+                status: this.statsProvider.getStatus(),
+            };
+            this.worker.postMessage(stats);
+        }
+        catch (err) {
+            console.error('[health-manager] Failed to send stats:', err);
+        }
+    }
+}
+/** Default health port offset from main port */
+export const HEALTH_PORT_OFFSET = 1;
+/**
+ * Calculate health port from main port
+ */
+export function getHealthPort(mainPort) {
+    return mainPort + HEALTH_PORT_OFFSET;
+}
+//# sourceMappingURL=health-worker-manager.js.map

package/dist/health-worker.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Health Check Worker Thread
+ *
+ * Runs a minimal HTTP server on a separate thread to handle health checks.
+ * This ensures health checks respond even when the main event loop is blocked
+ * by heavy compute tasks (builds, large file operations, etc.).
+ */
+export {};
+//# sourceMappingURL=health-worker.d.ts.map

package/dist/health-worker.js

@@ -0,0 +1,79 @@
+/**
+ * Health Check Worker Thread
+ *
+ * Runs a minimal HTTP server on a separate thread to handle health checks.
+ * This ensures health checks respond even when the main event loop is blocked
+ * by heavy compute tasks (builds, large file operations, etc.).
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import http from 'node:http';
+// Default stats until we receive updates from main thread
+let currentStats = {
+    uptime: 0,
+    memoryMB: 0,
+    relayConnected: false,
+    agentCount: 0,
+    status: 'healthy',
+};
+// Track when we last received stats from main thread
+let lastStatsUpdate = Date.now();
+const STATS_STALE_THRESHOLD_MS = 60_000; // 1 minute
+// Listen for stats updates from main thread
+if (parentPort) {
+    parentPort.on('message', (stats) => {
+        currentStats = stats;
+        lastStatsUpdate = Date.now();
+    });
+}
+const { port } = workerData;
+const server = http.createServer((req, res) => {
+    // Only handle /health endpoint
+    if (req.url !== '/health' && req.url !== '/') {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+        return;
+    }
+    // Check if stats are stale (main thread might be blocked)
+    const statsAge = Date.now() - lastStatsUpdate;
+    const isStale = statsAge > STATS_STALE_THRESHOLD_MS;
+    // Determine status
+    let status = currentStats.status;
+    if (isStale) {
+        status = 'busy'; // Main thread is likely blocked
+    }
+    const response = {
+        status,
+        uptime: currentStats.uptime,
+        memoryMB: currentStats.memoryMB,
+        relayConnected: currentStats.relayConnected,
+        agentCount: currentStats.agentCount,
+        statsAgeMs: statsAge,
+        worker: true, // Indicates response is from worker thread
+    };
+    // Return 200 for healthy/busy, 503 for degraded
+    const statusCode = status === 'degraded' ? 503 : 200;
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(response));
+});
+server.listen(port, '0.0.0.0', () => {
+    console.log(`[health-worker] Health check server listening on port ${port}`);
+    // Notify main thread we're ready
+    if (parentPort) {
+        parentPort.postMessage({ type: 'ready', port });
+    }
+});
+// Handle errors gracefully
+server.on('error', (err) => {
+    console.error('[health-worker] Server error:', err);
+    if (parentPort) {
+        parentPort.postMessage({ type: 'error', error: String(err) });
+    }
+});
+// Keep the worker alive
+process.on('uncaughtException', (err) => {
+    console.error('[health-worker] Uncaught exception:', err);
+});
+process.on('unhandledRejection', (err) => {
+    console.error('[health-worker] Unhandled rejection:', err);
+});
+//# sourceMappingURL=health-worker.js.map

package/dist/index.d.ts

@@ -8,5 +8,6 @@ export * from './wrapper/index.js';
 export * from './utils/index.js';
 export * from './hooks/index.js';
 export { type StoredMessage, type MessageQuery, type StorageAdapter, type StorageConfig, } from './storage/adapter.js';
-export { type MemoryAdapter, type MemoryEntry, type MemoryConfig, type MemoryService, type MemorySearchQuery, type AddMemoryOptions, type MemoryResult, createMemoryAdapter, createMemoryService, createMemoryHooks, getMemoryHooks, InMemoryAdapter, SupermemoryAdapter, } from './memory/index.js';
+export { type MemoryAdapter, type MemoryEntry, type MemoryConfig, type MemoryService, type MemorySearchQuery, type AddMemoryOptions, type MemoryResult, createMemoryAdapter, createMemoryService, createMemoryHooks, getMemoryHooks, InMemoryAdapter, SupermemoryAdapter, ContextCompactor, createContextCompactor, estimateTokens, estimateContextTokens, type CompactionConfig, type CompactionResult, } from './memory/index.js';
+export { type DLQStorageAdapter, type DeadLetter, type DLQConfig, type DLQStats, type DLQQuery, SQLiteDLQAdapter, PostgresDLQAdapter, InMemoryDLQAdapter, createDLQAdapter, DEFAULT_DLQ_CONFIG, } from './storage/dlq-adapter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,5 +8,9 @@ export * from './wrapper/index.js';
 export * from './utils/index.js';
 export * from './hooks/index.js';
 // Memory types and adapters for external consumers
-export { createMemoryAdapter, createMemoryService, createMemoryHooks, getMemoryHooks, InMemoryAdapter, SupermemoryAdapter, } from './memory/index.js';
+export { createMemoryAdapter, createMemoryService, createMemoryHooks, getMemoryHooks, InMemoryAdapter, SupermemoryAdapter, 
+// Context compaction
+ContextCompactor, createContextCompactor, estimateTokens, estimateContextTokens, } from './memory/index.js';
+// Dead Letter Queue adapters
+export { SQLiteDLQAdapter, PostgresDLQAdapter, InMemoryDLQAdapter, createDLQAdapter, DEFAULT_DLQ_CONFIG, } from './storage/dlq-adapter.js';
 //# sourceMappingURL=index.js.map