@poolzin/pool-bot 2026.3.7 → 2026.3.9

package/dist/context-engine/registry.js

@@ -0,0 +1,86 @@
+/**
+ * Context Engine Registry
+ *
+ * Manages available context engines and provides
+ * factory methods for creating engine instances.
+ */
+export class ContextEngineRegistry {
+    engines = new Map();
+    instances = new Map();
+    /**
+     * Register a new context engine
+     */
+    register(id, EngineClass) {
+        this.engines.set(id, EngineClass);
+    }
+    /**
+     * Check if an engine is registered
+     */
+    has(id) {
+        return this.engines.has(id);
+    }
+    /**
+     * Get available engine IDs
+     */
+    getAvailableEngines() {
+        return Array.from(this.engines.keys());
+    }
+    /**
+     * Create or get a cached engine instance
+     */
+    getEngine(id) {
+        // Return cached instance if exists
+        const cached = this.instances.get(id);
+        if (cached) {
+            return cached;
+        }
+        // Create new instance
+        const EngineClass = this.engines.get(id);
+        if (!EngineClass) {
+            throw new Error(`Context engine "${id}" not registered. Available: ${this.getAvailableEngines().join(", ")}`);
+        }
+        const instance = new EngineClass();
+        this.instances.set(id, instance);
+        return instance;
+    }
+    /**
+     * Remove cached instance (for cleanup/testing)
+     */
+    clearCache(id) {
+        if (id) {
+            this.instances.delete(id);
+        }
+        else {
+            this.instances.clear();
+        }
+    }
+    /**
+     * Get engine info for all registered engines
+     */
+    getEngineInfos() {
+        return this.getAvailableEngines().map((id) => {
+            const engine = this.getEngine(id);
+            return {
+                id,
+                name: engine.info.name,
+                description: engine.info.description,
+            };
+        });
+    }
+}
+/**
+ * Global registry instance
+ */
+export const globalContextEngineRegistry = new ContextEngineRegistry();
+/**
+ * Resolve which engine to use based on configuration
+ */
+export function resolveContextEngine(sessionId, config, registry = globalContextEngineRegistry) {
+    // Check for session-specific override
+    const engineId = config.sessionEngines?.[sessionId] ?? config.defaultEngine;
+    if (!registry.has(engineId)) {
+        throw new Error(`Context engine "${engineId}" not found for session ${sessionId}. ` +
+            `Available engines: ${registry.getAvailableEngines().join(", ")}`);
+    }
+    return registry.getEngine(engineId);
+}

package/dist/context-engine/summarizing.js

@@ -0,0 +1,293 @@
+/**
+ * Summarizing Context Engine
+ *
+ * Advanced context management with intelligent summarization.
+ * Provides better token efficiency than the legacy engine.
+ *
+ * Features:
+ * - Sliding window with summarization
+ * - Token-aware message prioritization
+ * - Configurable summarization strategy
+ */
+/**
+ * Token estimator using character-based approximation
+ * More accurate than simple division
+ */
+function estimateTokens(text) {
+    // GPT-style tokenization approximation
+    // - Average English word: ~1.3 tokens
+    // - Whitespace and punctuation: ~0.5 tokens each
+    // - Code/non-English: ~2-3 tokens per word
+    const words = text.trim().split(/\s+/).length;
+    const chars = text.length;
+    const punctuation = (text.match(/[.,!?;:()[\]{}"']/g) ?? []).length;
+    // Heuristic: code detection (high special char ratio)
+    const specialChars = (text.match(/[^\w\s]/g) ?? []).length;
+    const isCode = specialChars / chars > 0.15;
+    if (isCode) {
+        return Math.ceil(chars / 2.5); // Code: ~2.5 chars/token
+    }
+    // Regular text estimation
+    const wordTokens = words * 1.3;
+    const punctTokens = punctuation * 0.5;
+    const overhead = Math.ceil(chars / 100); // Metadata overhead
+    return Math.ceil(wordTokens + punctTokens + overhead);
+}
+/**
+ * Summarizing Context Engine
+ *
+ * Implements sliding window with intelligent summarization:
+ * 1. Keep system messages (highest priority)
+ * 2. Keep recent conversation (high priority)
+ * 3. Summarize older messages into running summary
+ */
+export class SummarizingContextEngine {
+    info = {
+        id: "summarizing",
+        name: "Summarizing Context Engine",
+        description: "Sliding window with intelligent message summarization",
+        supportsVectorSearch: false,
+        supportsFullTextSearch: false,
+        tokenLimit: undefined,
+    };
+    config;
+    sessions = new Map();
+    constructor(config) {
+        this.config = {
+            maxTokens: config?.maxTokens ?? 8000,
+            keepRecentMessages: config?.keepRecentMessages ?? 6,
+            summarizationThreshold: config?.summarizationThreshold ?? 4000,
+        };
+    }
+    async bootstrap(params) {
+        try {
+            this.sessions.set(params.sessionId, {
+                messages: [],
+                summary: undefined,
+                summaryTokens: 0,
+                lastAccessed: new Date(),
+                totalIngested: 0,
+            });
+            return { success: true };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async ingest(params) {
+        try {
+            const session = this.sessions.get(params.sessionId);
+            if (!session) {
+                return {
+                    success: false,
+                    error: `Session ${params.sessionId} not found`,
+                };
+            }
+            const content = typeof params.message.content === "string"
+                ? params.message.content
+                : JSON.stringify(params.message.content);
+            const estimatedTokens = estimateTokens(content);
+            // Calculate priority
+            const priority = this.calculatePriority(params.message, session.messages.length);
+            const prioritized = {
+                ...params.message,
+                priority,
+                estimatedTokens,
+                internalTimestamp: Date.now(),
+            };
+            session.messages.push(prioritized);
+            session.totalIngested++;
+            session.lastAccessed = new Date();
+            // Check if we need to compact
+            const currentTokens = this.getTotalTokenCount(session);
+            if (currentTokens > this.config.summarizationThreshold) {
+                await this.compact({ sessionId: params.sessionId });
+            }
+            return {
+                success: true,
+                tokensConsumed: estimatedTokens,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async assemble(params) {
+        const session = this.sessions.get(params.sessionId);
+        if (!session) {
+            return {
+                messages: params.messages ?? [],
+                totalTokens: 0,
+                wasTruncated: false,
+            };
+        }
+        // Build context: summary + recent messages
+        const resultMessages = [];
+        let totalTokens = 0;
+        // Add summary if exists
+        if (session.summary) {
+            const summaryMsg = {
+                role: "system",
+                content: `[Previous conversation summary: ${session.summary}]`,
+                metadata: { isSummary: true },
+            };
+            resultMessages.push(summaryMsg);
+            totalTokens += session.summaryTokens;
+        }
+        // Add messages within budget
+        const budget = params.tokenBudget ?? this.config.maxTokens;
+        const sortedMessages = [...session.messages].sort((a, b) => b.priority - a.priority || a.internalTimestamp - b.internalTimestamp);
+        const included = [];
+        const excluded = [];
+        for (const msg of sortedMessages) {
+            if (totalTokens + msg.estimatedTokens <= budget) {
+                // Strip priority metadata before returning
+                const { priority: _, estimatedTokens: __, internalTimestamp: ___, ...cleanMsg } = msg;
+                included.push(cleanMsg);
+                totalTokens += msg.estimatedTokens;
+            }
+            else {
+                const { priority: _, estimatedTokens: __, internalTimestamp: ___, ...cleanMsg } = msg;
+                excluded.push(cleanMsg);
+            }
+        }
+        // Sort by internalTimestamp for final output
+        included.sort((a, b) => {
+            const ta = session.messages.find(m => m.id === a.id)?.internalTimestamp ?? 0;
+            const tb = session.messages.find(m => m.id === b.id)?.internalTimestamp ?? 0;
+            return ta - tb;
+        });
+        resultMessages.push(...included);
+        return {
+            messages: resultMessages,
+            totalTokens,
+            wasTruncated: excluded.length > 0,
+            excludedMessages: excluded.length > 0 ? excluded : undefined,
+        };
+    }
+    async compact(params) {
+        try {
+            const session = this.sessions.get(params.sessionId);
+            if (!session || session.messages.length <= this.config.keepRecentMessages) {
+                return { success: true, tokensSaved: 0 };
+            }
+            const originalTokens = this.getTotalTokenCount(session);
+            // Messages to summarize (older ones)
+            const toSummarize = session.messages.slice(0, -this.config.keepRecentMessages);
+            const toKeep = session.messages.slice(-this.config.keepRecentMessages);
+            if (toSummarize.length === 0) {
+                return { success: true, tokensSaved: 0 };
+            }
+            // Generate summary (simplified - in production, use LLM)
+            const summary = this.generateSummary(toSummarize);
+            const _summaryTokens = estimateTokens(summary);
+            // Update session
+            session.summary = session.summary
+                ? `${session.summary} ${summary}`
+                : summary;
+            session.summaryTokens = estimateTokens(session.summary);
+            session.messages = toKeep;
+            const newTokens = this.getTotalTokenCount(session);
+            const tokensSaved = originalTokens - newTokens;
+            return {
+                success: true,
+                summary: session.summary,
+                tokensSaved: Math.max(0, tokensSaved),
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async cleanup(params) {
+        this.sessions.delete(params.sessionId);
+    }
+    async getStats(params) {
+        const session = this.sessions.get(params.sessionId);
+        if (!session) {
+            return { messageCount: 0 };
+        }
+        return {
+            messageCount: session.messages.length,
+            totalTokens: this.getTotalTokenCount(session),
+            lastAccessed: session.lastAccessed,
+        };
+    }
+    /**
+     * Calculate message priority (0-100)
+     */
+    calculatePriority(message, index) {
+        let priority = 50; // Base priority
+        // System messages are highest priority
+        if (message.role === "system") {
+            priority += 40;
+        }
+        // Recent messages get boost
+        if (index > -5) {
+            priority += 20;
+        }
+        // Messages with tool calls/results are important
+        if (message.metadata?.tool_calls ||
+            message.metadata?.tool_call_id) {
+            priority += 15;
+        }
+        return Math.min(100, priority);
+    }
+    /**
+     * Get total token count for session
+     */
+    getTotalTokenCount(session) {
+        const messageTokens = session.messages.reduce((sum, m) => sum + m.estimatedTokens, 0);
+        return messageTokens + session.summaryTokens;
+    }
+    /**
+     * Generate a simple summary of messages
+     * In production, this would use an LLM
+     */
+    generateSummary(messages) {
+        const userMsgs = messages.filter((m) => m.role === "user");
+        const assistantMsgs = messages.filter((m) => m.role === "assistant");
+        const topics = this.extractTopics(messages);
+        return (`Conversation covered ${userMsgs.length} user queries and ${assistantMsgs.length} responses. ` +
+            `Topics: ${topics.join(", ") || "general discussion"}.`);
+    }
+    /**
+     * Extract key topics from messages (simplified)
+     */
+    extractTopics(messages) {
+        const allContent = messages
+            .map((m) => typeof m.content === "string" ? m.content : JSON.stringify(m.content))
+            .join(" ")
+            .toLowerCase();
+        // Simple keyword extraction
+        const keywords = [
+            "code",
+            "function",
+            "error",
+            "bug",
+            "fix",
+            "implement",
+            "create",
+            "update",
+            "delete",
+            "configure",
+            "setup",
+        ];
+        return keywords.filter((kw) => allContent.includes(kw)).slice(0, 3);
+    }
+}
+/**
+ * Create a summarizing context engine
+ */
+export function createSummarizingContextEngine(config) {
+    return new SummarizingContextEngine(config);
+}

package/dist/context-engine/types.js

@@ -0,0 +1,7 @@
+/**
+ * Context Engine - Pluggable conversation context management
+ *
+ * Provides a modular architecture for managing conversation context
+ * with support for different storage and retrieval strategies.
+ */
+export {};

package/dist/infra/abort-pattern.js

@@ -0,0 +1,106 @@
+/**
+ * Abort Pattern Utilities
+ *
+ * Provides memory-leak-free abort signal handling.
+ *
+ * CRITICAL FIX: Uses `.bind()` instead of closures to prevent memory leaks.
+ * Issue #7174: Closure-based abort handlers capture scope and leak memory.
+ *
+ * @example
+ * ```typescript
+ * // BAD: Captures closure scope (leaks memory)
+ * signal.addEventListener('abort', () => controller.abort());
+ *
+ * // GOOD: No closure capture
+ * signal.addEventListener('abort', relayAbort.bind(controller));
+ * ```
+ */
+/**
+ * Relay abort signal without closure capture
+ * Prevents memory leak by using bind instead of arrow function
+ */
+export function relayAbort() {
+    this.abort();
+}
+/**
+ * Create an abort relay that doesn't capture closure scope
+ */
+export function createAbortRelay(controller) {
+    return relayAbort.bind(controller);
+}
+/**
+ * Link an abort signal to a controller without memory leaks
+ */
+export function linkAbortSignal(source, target) {
+    const handler = createAbortRelay(target);
+    source.addEventListener('abort', handler, { once: true });
+    // Return cleanup function
+    return () => {
+        source.removeEventListener('abort', handler);
+    };
+}
+/**
+ * Create a timeout-based abort controller
+ */
+export function createTimeoutAbortController(timeoutMs) {
+    const controller = new AbortController();
+    if (timeoutMs > 0) {
+        const timeout = setTimeout(() => {
+            controller.abort();
+        }, timeoutMs);
+        return {
+            controller,
+            cleanup: () => clearTimeout(timeout),
+        };
+    }
+    return {
+        controller,
+        cleanup: () => { },
+    };
+}
+/**
+ * Race multiple abort signals
+ */
+export function raceAbortSignals(signals, controller) {
+    const handlers = [];
+    let alreadyAborted = false;
+    for (const signal of signals) {
+        if (signal.aborted && !alreadyAborted) {
+            alreadyAborted = true;
+            controller.abort();
+        }
+        else if (!alreadyAborted) {
+            const handler = createAbortRelay(controller);
+            signal.addEventListener('abort', handler, { once: true });
+            handlers.push(() => signal.removeEventListener('abort', handler));
+        }
+    }
+    return () => {
+        for (const cleanup of handlers) {
+            cleanup();
+        }
+    };
+}
+/**
+ * Fetch with timeout and proper abort handling
+ */
+export async function fetchWithTimeout(url, options = {}) {
+    const { timeoutMs = 30000, ...fetchOptions } = options;
+    const { controller, cleanup } = createTimeoutAbortController(timeoutMs);
+    // Link existing signal if provided
+    let unlink;
+    if (fetchOptions.signal) {
+        unlink = linkAbortSignal(fetchOptions.signal, controller);
+    }
+    try {
+        const response = await fetch(url, {
+            ...fetchOptions,
+            signal: controller.signal,
+        });
+        return response;
+    }
+    finally {
+        unlink?.();
+        cleanup();
+    }
+}

package/dist/infra/retry.js

@@ -85,5 +85,99 @@ export async function retryAsync(fn, attemptsOrOptions = 3, initialDelayMs = 300
             await sleep(delay);
         }
     }
+    options.onExhausted?.(lastErr, maxAttempts);
     throw lastErr ?? new Error("Retry failed");
 }
+/**
+ * Execute a function with retry logic and return detailed result
+ */
+export async function retryWithResult(fn, options = {}) {
+    const resolved = resolveRetryConfig(DEFAULT_RETRY_CONFIG, options);
+    const maxAttempts = resolved.attempts;
+    const minDelayMs = resolved.minDelayMs;
+    const maxDelayMs = Number.isFinite(resolved.maxDelayMs) ? resolved.maxDelayMs : Number.POSITIVE_INFINITY;
+    const jitter = resolved.jitter;
+    const shouldRetry = options.shouldRetry ?? (() => true);
+    let lastErr;
+    let totalDelayMs = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const result = await fn();
+            return { result, attempts: attempt, totalDelayMs };
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= maxAttempts || !shouldRetry(err, attempt)) {
+                break;
+            }
+            const retryAfterMs = options.retryAfterMs?.(err);
+            const hasRetryAfter = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs);
+            const baseDelay = hasRetryAfter
+                ? Math.max(retryAfterMs, minDelayMs)
+                : minDelayMs * 2 ** (attempt - 1);
+            let delay = Math.min(baseDelay, maxDelayMs);
+            delay = applyJitter(delay, jitter);
+            delay = Math.min(Math.max(delay, minDelayMs), maxDelayMs);
+            totalDelayMs += delay;
+            options.onRetry?.({
+                attempt,
+                maxAttempts,
+                delayMs: delay,
+                err,
+                label: options.label,
+            });
+            await sleep(delay);
+        }
+    }
+    options.onExhausted?.(lastErr, maxAttempts);
+    throw lastErr ?? new Error("Retry failed");
+}
+/**
+ * Check if error is retryable (network errors, rate limits, etc.)
+ */
+export function isRetryableError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        // Network errors
+        if (message.includes("econnreset"))
+            return true;
+        if (message.includes("etimedout"))
+            return true;
+        if (message.includes("econnrefused"))
+            return true;
+        if (message.includes("enotfound"))
+            return true;
+        if (message.includes("network"))
+            return true;
+        if (message.includes("timeout"))
+            return true;
+        // HTTP status codes that are retryable
+        const statusMatch = error.message.match(/status\s+(\d+)/i);
+        if (statusMatch) {
+            const status = parseInt(statusMatch[1], 10);
+            // 429 = Too Many Requests, 502/503/504 = Gateway errors
+            if (status === 429 || status === 502 || status === 503 || status === 504) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Default retry configuration for API calls
+ */
+export const API_RETRY_CONFIG = {
+    attempts: 3,
+    minDelayMs: 1000,
+    maxDelayMs: 10000,
+    jitter: 0.1,
+};
+/**
+ * Default retry configuration for network calls
+ */
+export const NETWORK_RETRY_CONFIG = {
+    attempts: 5,
+    minDelayMs: 500,
+    maxDelayMs: 30000,
+    jitter: 0.1,
+};

package/dist/secrets/index.js

@@ -0,0 +1,28 @@
+/**
+ * Secrets Management System
+ *
+ * Secure secret resolution with support for:
+ * - Environment variables (env:default:KEY)
+ * - JSON files (file:/path/to/secrets.json:key)
+ * - Direct values (backward compatible)
+ *
+ * @example
+ * ```typescript
+ * import { SecretsRuntime, resolveValue } from './secrets/index.js';
+ *
+ * // Create runtime
+ * const runtime = new SecretsRuntime({
+ *   allowDirectValues: true,
+ *   warnOnDirectValues: true
+ * });
+ *
+ * // Resolve API key
+ * runtime.resolve('openaiApiKey', 'env:default:OPENAI_API_KEY');
+ *
+ * // Get resolved value
+ * const apiKey = runtime.get('openaiApiKey');
+ * ```
+ */
+export * from "./types.js";
+export * from "./resolver.js";
+export * from "./runtime.js";