agent-relay 1.3.1 → 1.3.3

package/dist/memory/context-compaction.js

@@ -0,0 +1,453 @@
+/**
+ * Context Compaction for Long Agent Sessions
+ *
+ * Manages conversation context to prevent token limit exhaustion.
+ * Provides token counting, message summarization, and context pruning.
+ *
+ * Inspired by russian-code-ts context management targets:
+ * - Token estimation: <20ms
+ * - Embeddings-based semantic search for relevant context
+ *
+ * Strategies:
+ * 1. Fast token estimation (character-based heuristic)
+ * 2. Importance-weighted message retention
+ * 3. Sliding window with summary injection
+ * 4. Semantic deduplication of similar messages
+ */
+// =============================================================================
+// Default Configuration
+// =============================================================================
+const DEFAULT_CONFIG = {
+    maxTokens: 100000, // 100k tokens (Claude's typical limit)
+    targetUsage: 0.7, // Target 70% after compaction
+    compactionThreshold: 0.85, // Trigger at 85% usage
+    minImportanceRetain: 30, // Keep messages with importance >= 30
+    keepRecentCount: 10, // Always keep last 10 messages
+    enableSummarization: true,
+    enableDeduplication: true,
+    deduplicationThreshold: 0.85,
+};
+// =============================================================================
+// Token Estimation
+// =============================================================================
+/**
+ * Fast token estimation using character-based heuristic.
+ * Targets <20ms latency for large texts.
+ *
+ * Heuristic: ~4 characters per token for English text.
+ * Adjusts for code (more tokens per char) and whitespace.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    const length = text.length;
+    // Fast path for short texts
+    if (length < 100) {
+        return Math.ceil(length / 3.5);
+    }
+    // Sample-based estimation for longer texts
+    // Count different character types in sample
+    const sampleSize = Math.min(1000, length);
+    const sample = text.substring(0, sampleSize);
+    let codeChars = 0;
+    let whitespaceChars = 0;
+    let _punctuationChars = 0;
+    for (let i = 0; i < sample.length; i++) {
+        const char = sample[i];
+        if (/\s/.test(char)) {
+            whitespaceChars++;
+        }
+        else if (/[{}[\]();:,.<>!=+\-*/&|^~`@#$%]/.test(char)) {
+            _punctuationChars++;
+            codeChars++;
+        }
+    }
+    const codeRatio = codeChars / sampleSize;
+    const whitespaceRatio = whitespaceChars / sampleSize;
+    // Adjust chars per token based on content type
+    // Heuristics based on tokenization patterns:
+    // - Base prose: ~4 chars/token (average English text)
+    // - Code: ~3 chars/token (more tokens due to symbols/structure)
+    // - High whitespace: ~3.5 chars/token (more word boundaries = more tokens)
+    const baseCharsPerToken = 4;
+    const codeAdjustment = codeRatio * 1.5; // Code reduces chars/token (more tokens)
+    const whitespaceAdjustment = whitespaceRatio * 0.5; // Whitespace reduces chars/token (more word boundaries)
+    const charsPerToken = baseCharsPerToken - codeAdjustment - whitespaceAdjustment;
+    const adjustedCharsPerToken = Math.max(2.5, Math.min(5, charsPerToken));
+    return Math.ceil(length / adjustedCharsPerToken);
+}
+/**
+ * Estimate tokens for a message (uses caching).
+ */
+export function estimateMessageTokens(message) {
+    if (message.tokenCount !== undefined) {
+        return message.tokenCount;
+    }
+    // Role overhead: ~4 tokens for role markers
+    const roleOverhead = 4;
+    const contentTokens = estimateTokens(message.content);
+    message.tokenCount = roleOverhead + contentTokens;
+    return message.tokenCount;
+}
+/**
+ * Estimate tokens for entire context.
+ */
+export function estimateContextTokens(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        total += estimateMessageTokens(msg);
+    }
+    // Add overhead for message separators (~2 tokens per message)
+    total += messages.length * 2;
+    return total;
+}
+// =============================================================================
+// Importance Scoring
+// =============================================================================
+/**
+ * Calculate importance score for a message.
+ * Higher scores = more important to retain.
+ */
+export function calculateImportance(message, index, total) {
+    let score = 50; // Base score
+    // Recency bonus (0-20 points)
+    const recencyRatio = index / total;
+    score += recencyRatio * 20;
+    // System messages are important
+    if (message.role === 'system') {
+        score += 30;
+    }
+    // Check for important content patterns
+    const content = message.content.toLowerCase();
+    // Task-related keywords
+    if (/\b(todo|task|implement|fix|bug|error|important|critical|urgent)\b/.test(content)) {
+        score += 15;
+    }
+    // Code blocks are often important context
+    if (/```[\s\S]*```/.test(message.content)) {
+        score += 10;
+    }
+    // Questions that might need answers retained
+    if (/\?/.test(content) && message.role === 'user') {
+        score += 10;
+    }
+    // Acknowledgments and status updates can be lower priority
+    if (/^(ok|ack|got it|understood|done|completed)/i.test(content)) {
+        score -= 20;
+    }
+    // Very short messages are usually less important
+    if (message.content.length < 50) {
+        score -= 10;
+    }
+    // Summaries should be kept
+    if (message.isSummary) {
+        score += 25;
+    }
+    // User-specified importance overrides
+    if (message.importance !== undefined) {
+        score = (score + message.importance) / 2;
+    }
+    return Math.max(0, Math.min(100, score));
+}
+// =============================================================================
+// Similarity Detection
+// =============================================================================
+/**
+ * Simple similarity score between two strings (Jaccard on word set).
+ * Returns 0-1 where 1 = identical.
+ */
+export function calculateSimilarity(a, b) {
+    const wordsA = new Set(a.toLowerCase().split(/\s+/).filter(w => w.length > 2));
+    const wordsB = new Set(b.toLowerCase().split(/\s+/).filter(w => w.length > 2));
+    if (wordsA.size === 0 || wordsB.size === 0) {
+        return 0;
+    }
+    let intersection = 0;
+    for (const word of wordsA) {
+        if (wordsB.has(word)) {
+            intersection++;
+        }
+    }
+    const union = wordsA.size + wordsB.size - intersection;
+    return intersection / union;
+}
+/**
+ * Find duplicate/similar messages.
+ */
+export function findDuplicates(messages, threshold = 0.85) {
+    const duplicates = new Map();
+    for (let i = 0; i < messages.length; i++) {
+        for (let j = i + 1; j < messages.length; j++) {
+            const similarity = calculateSimilarity(messages[i].content, messages[j].content);
+            if (similarity >= threshold) {
+                const key = messages[i].id;
+                const existing = duplicates.get(key) ?? [];
+                existing.push(messages[j].id);
+                duplicates.set(key, existing);
+            }
+        }
+    }
+    return duplicates;
+}
+// =============================================================================
+// Summarization
+// =============================================================================
+/**
+ * Create a summary of multiple messages.
+ * This is a simple extractive summary - in production, use an LLM.
+ */
+export function createSummary(messages) {
+    const messageCount = messages.length;
+    const roles = new Set(messages.map(m => m.role));
+    const threads = new Set(messages.filter(m => m.thread).map(m => m.thread));
+    // Extract key sentences (first sentence of each message, or first 100 chars)
+    const keyPoints = [];
+    for (const msg of messages.slice(0, 5)) { // Take up to 5 key points
+        const firstSentence = msg.content.split(/[.!?]\s/)[0];
+        if (firstSentence && firstSentence.length < 200) {
+            keyPoints.push(`- ${firstSentence}`);
+        }
+    }
+    const content = [
+        `[Summary of ${messageCount} messages]`,
+        `Participants: ${Array.from(roles).join(', ')}`,
+        threads.size > 0 ? `Threads: ${Array.from(threads).join(', ')}` : '',
+        'Key points:',
+        ...keyPoints,
+        `[End summary]`,
+    ].filter(Boolean).join('\n');
+    return {
+        id: `summary_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+        role: 'system',
+        content,
+        timestamp: Date.now(),
+        importance: 70,
+        isSummary: true,
+        summarizes: messages.map(m => m.id),
+    };
+}
+// =============================================================================
+// Context Compaction
+// =============================================================================
+/**
+ * Context compaction manager.
+ */
+export class ContextCompactor {
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Get current context window status.
+     */
+    getContextWindow(messages) {
+        const totalTokens = estimateContextTokens(messages);
+        return {
+            messages,
+            totalTokens,
+            maxTokens: this.config.maxTokens,
+            usagePercent: totalTokens / this.config.maxTokens,
+        };
+    }
+    /**
+     * Check if compaction is needed.
+     */
+    needsCompaction(messages) {
+        const window = this.getContextWindow(messages);
+        return window.usagePercent >= this.config.compactionThreshold;
+    }
+    /**
+     * Perform context compaction.
+     */
+    compact(messages) {
+        const window = this.getContextWindow(messages);
+        // No compaction needed
+        if (window.usagePercent < this.config.compactionThreshold) {
+            return {
+                messages,
+                messagesRemoved: 0,
+                tokensSaved: 0,
+                strategy: 'none',
+            };
+        }
+        const targetTokens = Math.floor(this.config.maxTokens * this.config.targetUsage);
+        let result = [...messages];
+        let strategy = 'none';
+        const originalTokens = window.totalTokens;
+        // Calculate importance for all messages
+        const importanceMap = new Map();
+        for (let i = 0; i < result.length; i++) {
+            importanceMap.set(result[i].id, calculateImportance(result[i], i, result.length));
+        }
+        // Strategy 1: Deduplicate similar messages
+        if (this.config.enableDeduplication) {
+            const duplicates = findDuplicates(result, this.config.deduplicationThreshold);
+            if (duplicates.size > 0) {
+                const toRemove = new Set();
+                for (const [, dups] of duplicates) {
+                    for (const id of dups) {
+                        toRemove.add(id);
+                    }
+                }
+                result = result.filter(m => !toRemove.has(m.id));
+                if (toRemove.size > 0) {
+                    strategy = 'deduplicate';
+                }
+            }
+        }
+        // Check if we've met target
+        if (estimateContextTokens(result) <= targetTokens) {
+            return {
+                messages: result,
+                messagesRemoved: messages.length - result.length,
+                tokensSaved: originalTokens - estimateContextTokens(result),
+                strategy,
+            };
+        }
+        // Strategy 2: Remove low-importance messages (keep recent)
+        const recentIds = new Set(result.slice(-this.config.keepRecentCount).map(m => m.id));
+        result = result.filter(m => {
+            if (recentIds.has(m.id))
+                return true;
+            if (m.isSummary)
+                return true;
+            if (m.role === 'system')
+                return true;
+            const importance = importanceMap.get(m.id) ?? 50;
+            return importance >= this.config.minImportanceRetain;
+        });
+        if (result.length < messages.length) {
+            strategy = 'trim_low_importance';
+        }
+        // Check if we've met target
+        if (estimateContextTokens(result) <= targetTokens) {
+            return {
+                messages: result,
+                messagesRemoved: messages.length - result.length,
+                tokensSaved: originalTokens - estimateContextTokens(result),
+                strategy,
+            };
+        }
+        // Strategy 3: Summarize old messages
+        if (this.config.enableSummarization) {
+            const messagesToSummarize = result.slice(0, -this.config.keepRecentCount)
+                .filter(m => !m.isSummary && m.role !== 'system');
+            if (messagesToSummarize.length >= 3) {
+                const summary = createSummary(messagesToSummarize);
+                const summaryIds = new Set(messagesToSummarize.map(m => m.id));
+                result = [
+                    summary,
+                    ...result.filter(m => !summaryIds.has(m.id)),
+                ];
+                strategy = 'summarize';
+                return {
+                    messages: result,
+                    messagesRemoved: messages.length - result.length,
+                    tokensSaved: originalTokens - estimateContextTokens(result),
+                    summaryAdded: summary,
+                    strategy,
+                };
+            }
+        }
+        // Strategy 4: Aggressive trim (last resort)
+        while (estimateContextTokens(result) > targetTokens && result.length > this.config.keepRecentCount + 1) {
+            // Remove oldest non-system, non-summary message
+            const removeIndex = result.findIndex(m => !m.isSummary && m.role !== 'system');
+            if (removeIndex === -1)
+                break;
+            result.splice(removeIndex, 1);
+        }
+        strategy = 'aggressive';
+        return {
+            messages: result,
+            messagesRemoved: messages.length - result.length,
+            tokensSaved: originalTokens - estimateContextTokens(result),
+            strategy,
+        };
+    }
+    /**
+     * Add a message to context with automatic compaction if needed.
+     */
+    addMessage(messages, newMessage) {
+        const updated = [...messages, newMessage];
+        if (this.needsCompaction(updated)) {
+            const result = this.compact(updated);
+            return {
+                messages: result.messages,
+                compacted: true,
+                result,
+            };
+        }
+        return {
+            messages: updated,
+            compacted: false,
+        };
+    }
+    /**
+     * Get token budget remaining.
+     */
+    getTokenBudget(messages) {
+        const used = estimateContextTokens(messages);
+        return {
+            used,
+            remaining: this.config.maxTokens - used,
+            percentUsed: (used / this.config.maxTokens) * 100,
+        };
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a context compactor with the given configuration.
+ */
+export function createContextCompactor(config) {
+    return new ContextCompactor(config);
+}
+// =============================================================================
+// Utilities
+// =============================================================================
+/**
+ * Format token count for display.
+ */
+export function formatTokenCount(tokens) {
+    if (tokens >= 1000000) {
+        return `${(tokens / 1000000).toFixed(1)}M`;
+    }
+    if (tokens >= 1000) {
+        return `${(tokens / 1000).toFixed(1)}k`;
+    }
+    return tokens.toString();
+}
+/**
+ * Benchmark token estimation performance.
+ */
+export function benchmarkTokenEstimation(iterations = 10000) {
+    const testTexts = [
+        'Hello world',
+        'This is a longer piece of text that contains multiple sentences and should take more time to process.',
+        '```typescript\nfunction hello() {\n  console.log("Hello");\n}\n```',
+        'A'.repeat(10000), // 10k chars
+    ];
+    let maxNs = 0;
+    let totalTokens = 0;
+    const start = process.hrtime.bigint();
+    for (let i = 0; i < iterations; i++) {
+        for (const text of testTexts) {
+            const s = process.hrtime.bigint();
+            const tokens = estimateTokens(text);
+            totalTokens += tokens;
+            const elapsed = Number(process.hrtime.bigint() - s);
+            if (elapsed > maxNs)
+                maxNs = elapsed;
+        }
+    }
+    const totalNs = Number(process.hrtime.bigint() - start);
+    const totalMs = totalNs / 1_000_000;
+    return {
+        avgNs: totalNs / (iterations * testTexts.length),
+        maxNs,
+        tokensPerMs: totalTokens / totalMs,
+    };
+}
+//# sourceMappingURL=context-compaction.js.map

package/dist/memory/index.d.ts

@@ -29,4 +29,5 @@ export * from './adapters/index.js';
 export { createMemoryAdapter, getMemoryConfigFromEnv } from './factory.js';
 export { createMemoryService } from './service.js';
 export { createMemoryHooks, getMemoryHooks } from './memory-hooks.js';
+export * from './context-compaction.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/memory/index.js

@@ -29,4 +29,5 @@ export * from './adapters/index.js';
 export { createMemoryAdapter, getMemoryConfigFromEnv } from './factory.js';
 export { createMemoryService } from './service.js';
 export { createMemoryHooks, getMemoryHooks } from './memory-hooks.js';
+export * from './context-compaction.js';
 //# sourceMappingURL=index.js.map

package/dist/protocol/channels.js

@@ -6,7 +6,7 @@
  * - Channels for group communication
  * - Direct messaging between any combination of users and agents
  */
-import { v4 as uuid } from 'uuid';
+import { generateId } from '../utils/id-generator.js';
 import { PROTOCOL_VERSION } from './types.js';
 // Re-export PROTOCOL_VERSION for convenience
 export { PROTOCOL_VERSION };
@@ -48,7 +48,7 @@ export function createChannelJoinEnvelope(from, channel, options) {
     return {
         v: PROTOCOL_VERSION,
         type: 'CHANNEL_JOIN',
-        id: uuid(),
+        id: generateId(),
         ts: Date.now(),
         from,
         payload: {
@@ -65,7 +65,7 @@ export function createChannelLeaveEnvelope(from, channel, reason) {
     return {
         v: PROTOCOL_VERSION,
         type: 'CHANNEL_LEAVE',
-        id: uuid(),
+        id: generateId(),
         ts: Date.now(),
         from,
         payload: {
@@ -81,7 +81,7 @@ export function createChannelMessageEnvelope(from, channel, body, options) {
     return {
         v: PROTOCOL_VERSION,
         type: 'CHANNEL_MESSAGE',
-        id: uuid(),
+        id: generateId(),
         ts: Date.now(),
         from,
         payload: {

package/dist/protocol/framing.d.ts

@@ -1,32 +1,94 @@
 /**
  * Frame encoding/decoding for the agent relay protocol.
- * Uses 4-byte big-endian length prefix + UTF-8 JSON.
+ *
+ * Wire format:
+ * - 1 byte: format indicator (0 = JSON, 1 = MessagePack)
+ * - 4 bytes: big-endian payload length
+ * - N bytes: payload (JSON or MessagePack encoded)
+ *
+ * Optimizations:
+ * - Ring buffer to avoid Buffer.concat allocations
+ * - MessagePack support for faster serialization (optional)
+ * - Zero-copy frame extraction where possible
  */
 import type { Envelope } from './types.js';
 export declare const MAX_FRAME_BYTES: number;
-export declare const HEADER_SIZE = 4;
+export declare const HEADER_SIZE = 5;
+export declare const LEGACY_HEADER_SIZE = 4;
+export type WireFormat = 'json' | 'msgpack';
+/**
+ * Initialize MessagePack support. Call this at startup if you want msgpack.
+ * Install @msgpack/msgpack to enable: npm install @msgpack/msgpack
+ */
+export declare function initMessagePack(): Promise<boolean>;
+/**
+ * Check if MessagePack is available.
+ */
+export declare function hasMessagePack(): boolean;
 /**
  * Encode a message envelope into a framed buffer.
+ *
+ * @param envelope - The envelope to encode
+ * @param format - Wire format to use (default: 'json')
+ * @returns Framed buffer ready for socket write
+ */
+export declare function encodeFrame(envelope: Envelope, format?: WireFormat): Buffer;
+/**
+ * Encode a frame in legacy format (no format byte, JSON only).
+ * Used for backwards compatibility with older clients.
  */
-export declare function encodeFrame(envelope: Envelope): Buffer;
+export declare function encodeFrameLegacy(envelope: Envelope): Buffer;
 /**
- * Frame parser state machine for streaming data.
+ * Ring buffer-based frame parser for streaming data.
+ *
+ * Optimizations:
+ * - Pre-allocated buffer avoids GC pressure from Buffer.concat
+ * - Compaction only when necessary (wrap-around)
+ * - Direct parsing from buffer offsets
  */
 export declare class FrameParser {
-    private buffer;
-    private maxFrameBytes;
+    private ring;
+    private head;
+    private tail;
+    private readonly capacity;
+    private readonly maxFrameBytes;
+    private format;
+    private legacyMode;
     constructor(maxFrameBytes?: number);
+    /**
+     * Set the expected wire format for parsing.
+     */
+    setFormat(format: WireFormat): void;
+    /**
+     * Enable legacy mode (4-byte header, JSON only).
+     */
+    setLegacyMode(legacy: boolean): void;
+    /**
+     * Get current unread bytes in buffer.
+     */
+    get pendingBytes(): number;
     /**
      * Push data into the parser and extract complete frames.
+     *
+     * @param data - Incoming data buffer
+     * @returns Array of parsed envelope frames
      */
     push(data: Buffer): Envelope[];
     /**
-     * Reset parser state (e.g., on connection reset).
+     * Extract all complete frames from the buffer.
      */
-    reset(): void;
+    private extractFrames;
     /**
-     * Get current buffer size (for debugging).
+     * Decode payload based on format byte.
      */
-    get pendingBytes(): number;
+    private decodePayload;
+    /**
+     * Compact the buffer by shifting unread data to the start.
+     */
+    private compact;
+    /**
+     * Reset parser state (e.g., on connection reset).
+     */
+    reset(): void;
 }
 //# sourceMappingURL=framing.d.ts.map