@poolzin/pool-bot 2026.2.10 → 2026.2.17

package/dist/memory/mmr.js

@@ -0,0 +1,164 @@
+/**
+ * Maximal Marginal Relevance (MMR) re-ranking algorithm.
+ *
+ * MMR balances relevance with diversity by iteratively selecting results
+ * that maximize: λ * relevance - (1-λ) * max_similarity_to_selected
+ *
+ * @see Carbonell & Goldstein, "The Use of MMR, Diversity-Based Reranking" (1998)
+ */
+export const DEFAULT_MMR_CONFIG = {
+    enabled: false,
+    lambda: 0.7,
+};
+/**
+ * Tokenize text for Jaccard similarity computation.
+ * Extracts alphanumeric tokens and normalizes to lowercase.
+ */
+export function tokenize(text) {
+    const tokens = text.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+    return new Set(tokens);
+}
+/**
+ * Compute Jaccard similarity between two token sets.
+ * Returns a value in [0, 1] where 1 means identical sets.
+ */
+export function jaccardSimilarity(setA, setB) {
+    if (setA.size === 0 && setB.size === 0) {
+        return 1;
+    }
+    if (setA.size === 0 || setB.size === 0) {
+        return 0;
+    }
+    let intersectionSize = 0;
+    const smaller = setA.size <= setB.size ? setA : setB;
+    const larger = setA.size <= setB.size ? setB : setA;
+    for (const token of smaller) {
+        if (larger.has(token)) {
+            intersectionSize++;
+        }
+    }
+    const unionSize = setA.size + setB.size - intersectionSize;
+    return unionSize === 0 ? 0 : intersectionSize / unionSize;
+}
+/**
+ * Compute text similarity between two content strings using Jaccard on tokens.
+ */
+export function textSimilarity(contentA, contentB) {
+    return jaccardSimilarity(tokenize(contentA), tokenize(contentB));
+}
+/**
+ * Compute the maximum similarity between an item and all selected items.
+ */
+function maxSimilarityToSelected(item, selectedItems, tokenCache) {
+    if (selectedItems.length === 0) {
+        return 0;
+    }
+    let maxSim = 0;
+    const itemTokens = tokenCache.get(item.id) ?? tokenize(item.content);
+    for (const selected of selectedItems) {
+        const selectedTokens = tokenCache.get(selected.id) ?? tokenize(selected.content);
+        const sim = jaccardSimilarity(itemTokens, selectedTokens);
+        if (sim > maxSim) {
+            maxSim = sim;
+        }
+    }
+    return maxSim;
+}
+/**
+ * Compute MMR score for a candidate item.
+ * MMR = λ * relevance - (1-λ) * max_similarity_to_selected
+ */
+export function computeMMRScore(relevance, maxSimilarity, lambda) {
+    return lambda * relevance - (1 - lambda) * maxSimilarity;
+}
+/**
+ * Re-rank items using Maximal Marginal Relevance (MMR).
+ *
+ * The algorithm iteratively selects items that balance relevance with diversity:
+ * 1. Start with the highest-scoring item
+ * 2. For each remaining slot, select the item that maximizes the MMR score
+ * 3. MMR score = λ * relevance - (1-λ) * max_similarity_to_already_selected
+ *
+ * @param items - Items to re-rank, must have score and content
+ * @param config - MMR configuration (lambda, enabled)
+ * @returns Re-ranked items in MMR order
+ */
+export function mmrRerank(items, config = {}) {
+    const { enabled = DEFAULT_MMR_CONFIG.enabled, lambda = DEFAULT_MMR_CONFIG.lambda } = config;
+    // Early exits
+    if (!enabled || items.length <= 1) {
+        return [...items];
+    }
+    // Clamp lambda to valid range
+    const clampedLambda = Math.max(0, Math.min(1, lambda));
+    // If lambda is 1, just return sorted by relevance (no diversity penalty)
+    if (clampedLambda === 1) {
+        return [...items].toSorted((a, b) => b.score - a.score);
+    }
+    // Pre-tokenize all items for efficiency
+    const tokenCache = new Map();
+    for (const item of items) {
+        tokenCache.set(item.id, tokenize(item.content));
+    }
+    // Normalize scores to [0, 1] for fair comparison with similarity
+    const maxScore = Math.max(...items.map((i) => i.score));
+    const minScore = Math.min(...items.map((i) => i.score));
+    const scoreRange = maxScore - minScore;
+    const normalizeScore = (score) => {
+        if (scoreRange === 0) {
+            return 1; // All scores equal
+        }
+        return (score - minScore) / scoreRange;
+    };
+    const selected = [];
+    const remaining = new Set(items);
+    // Select items iteratively
+    while (remaining.size > 0) {
+        let bestItem = null;
+        let bestMMRScore = -Infinity;
+        for (const candidate of remaining) {
+            const normalizedRelevance = normalizeScore(candidate.score);
+            const maxSim = maxSimilarityToSelected(candidate, selected, tokenCache);
+            const mmrScore = computeMMRScore(normalizedRelevance, maxSim, clampedLambda);
+            // Use original score as tiebreaker (higher is better)
+            if (mmrScore > bestMMRScore ||
+                (mmrScore === bestMMRScore && candidate.score > (bestItem?.score ?? -Infinity))) {
+                bestMMRScore = mmrScore;
+                bestItem = candidate;
+            }
+        }
+        if (bestItem) {
+            selected.push(bestItem);
+            remaining.delete(bestItem);
+        }
+        else {
+            // Should never happen, but safety exit
+            break;
+        }
+    }
+    return selected;
+}
+/**
+ * Apply MMR re-ranking to hybrid search results.
+ * Adapts the generic MMR function to work with the hybrid search result format.
+ */
+export function applyMMRToHybridResults(results, config = {}) {
+    if (results.length === 0) {
+        return results;
+    }
+    // Create a map from ID to original item for type-safe retrieval
+    const itemById = new Map();
+    // Create MMR items with unique IDs
+    const mmrItems = results.map((r, index) => {
+        const id = `${r.path}:${r.startLine}:${index}`;
+        itemById.set(id, r);
+        return {
+            id,
+            score: r.score,
+            content: r.snippet,
+        };
+    });
+    const reranked = mmrRerank(mmrItems, config);
+    // Map back to original items using the ID
+    return reranked.map((item) => itemById.get(item.id));
+}

package/dist/memory/query-expansion.js

@@ -0,0 +1,331 @@
+/**
+ * Query expansion for FTS-only search mode.
+ *
+ * When no embedding provider is available, we fall back to FTS (full-text search).
+ * FTS works best with specific keywords, but users often ask conversational queries
+ * like "that thing we discussed yesterday" or "之前讨论的那个方案".
+ *
+ * This module extracts meaningful keywords from such queries to improve FTS results.
+ */
+// Common stop words that don't add search value
+const STOP_WORDS_EN = new Set([
+    // Articles and determiners
+    "a",
+    "an",
+    "the",
+    "this",
+    "that",
+    "these",
+    "those",
+    // Pronouns
+    "i",
+    "me",
+    "my",
+    "we",
+    "our",
+    "you",
+    "your",
+    "he",
+    "she",
+    "it",
+    "they",
+    "them",
+    // Common verbs
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "have",
+    "has",
+    "had",
+    "do",
+    "does",
+    "did",
+    "will",
+    "would",
+    "could",
+    "should",
+    "can",
+    "may",
+    "might",
+    // Prepositions
+    "in",
+    "on",
+    "at",
+    "to",
+    "for",
+    "of",
+    "with",
+    "by",
+    "from",
+    "about",
+    "into",
+    "through",
+    "during",
+    "before",
+    "after",
+    "above",
+    "below",
+    "between",
+    "under",
+    "over",
+    // Conjunctions
+    "and",
+    "or",
+    "but",
+    "if",
+    "then",
+    "because",
+    "as",
+    "while",
+    "when",
+    "where",
+    "what",
+    "which",
+    "who",
+    "how",
+    "why",
+    // Time references (vague, not useful for FTS)
+    "yesterday",
+    "today",
+    "tomorrow",
+    "earlier",
+    "later",
+    "recently",
+    "before",
+    "ago",
+    "just",
+    "now",
+    // Vague references
+    "thing",
+    "things",
+    "stuff",
+    "something",
+    "anything",
+    "everything",
+    "nothing",
+    // Question words
+    "please",
+    "help",
+    "find",
+    "show",
+    "get",
+    "tell",
+    "give",
+]);
+const STOP_WORDS_ZH = new Set([
+    // Pronouns
+    "我",
+    "我们",
+    "你",
+    "你们",
+    "他",
+    "她",
+    "它",
+    "他们",
+    "这",
+    "那",
+    "这个",
+    "那个",
+    "这些",
+    "那些",
+    // Auxiliary words
+    "的",
+    "了",
+    "着",
+    "过",
+    "得",
+    "地",
+    "吗",
+    "呢",
+    "吧",
+    "啊",
+    "呀",
+    "嘛",
+    "啦",
+    // Verbs (common, vague)
+    "是",
+    "有",
+    "在",
+    "被",
+    "把",
+    "给",
+    "让",
+    "用",
+    "到",
+    "去",
+    "来",
+    "做",
+    "说",
+    "看",
+    "找",
+    "想",
+    "要",
+    "能",
+    "会",
+    "可以",
+    // Prepositions and conjunctions
+    "和",
+    "与",
+    "或",
+    "但",
+    "但是",
+    "因为",
+    "所以",
+    "如果",
+    "虽然",
+    "而",
+    "也",
+    "都",
+    "就",
+    "还",
+    "又",
+    "再",
+    "才",
+    "只",
+    // Time (vague)
+    "之前",
+    "以前",
+    "之后",
+    "以后",
+    "刚才",
+    "现在",
+    "昨天",
+    "今天",
+    "明天",
+    "最近",
+    // Vague references
+    "东西",
+    "事情",
+    "事",
+    "什么",
+    "哪个",
+    "哪些",
+    "怎么",
+    "为什么",
+    "多少",
+    // Question/request words
+    "请",
+    "帮",
+    "帮忙",
+    "告诉",
+]);
+/**
+ * Check if a token looks like a meaningful keyword.
+ * Returns false for short tokens, numbers-only, etc.
+ */
+function isValidKeyword(token) {
+    if (!token || token.length === 0) {
+        return false;
+    }
+    // Skip very short English words (likely stop words or fragments)
+    if (/^[a-zA-Z]+$/.test(token) && token.length < 3) {
+        return false;
+    }
+    // Skip pure numbers (not useful for semantic search)
+    if (/^\d+$/.test(token)) {
+        return false;
+    }
+    // Skip tokens that are all punctuation
+    if (/^[\p{P}\p{S}]+$/u.test(token)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Simple tokenizer that handles both English and Chinese text.
+ * For Chinese, we do character-based splitting since we don't have a proper segmenter.
+ * For English, we split on whitespace and punctuation.
+ */
+function tokenize(text) {
+    const tokens = [];
+    const normalized = text.toLowerCase().trim();
+    // Split into segments (English words, Chinese character sequences, etc.)
+    const segments = normalized.split(/[\s\p{P}]+/u).filter(Boolean);
+    for (const segment of segments) {
+        // Check if segment contains CJK characters
+        if (/[\u4e00-\u9fff]/.test(segment)) {
+            // For Chinese, extract character n-grams (unigrams and bigrams)
+            const chars = Array.from(segment).filter((c) => /[\u4e00-\u9fff]/.test(c));
+            // Add individual characters
+            tokens.push(...chars);
+            // Add bigrams for better phrase matching
+            for (let i = 0; i < chars.length - 1; i++) {
+                tokens.push(chars[i] + chars[i + 1]);
+            }
+        }
+        else {
+            // For non-CJK, keep as single token
+            tokens.push(segment);
+        }
+    }
+    return tokens;
+}
+/**
+ * Extract keywords from a conversational query for FTS search.
+ *
+ * Examples:
+ * - "that thing we discussed about the API" → ["discussed", "API"]
+ * - "之前讨论的那个方案" → ["讨论", "方案"]
+ * - "what was the solution for the bug" → ["solution", "bug"]
+ */
+export function extractKeywords(query) {
+    const tokens = tokenize(query);
+    const keywords = [];
+    const seen = new Set();
+    for (const token of tokens) {
+        // Skip stop words
+        if (STOP_WORDS_EN.has(token) || STOP_WORDS_ZH.has(token)) {
+            continue;
+        }
+        // Skip invalid keywords
+        if (!isValidKeyword(token)) {
+            continue;
+        }
+        // Skip duplicates
+        if (seen.has(token)) {
+            continue;
+        }
+        seen.add(token);
+        keywords.push(token);
+    }
+    return keywords;
+}
+/**
+ * Expand a query for FTS search.
+ * Returns both the original query and extracted keywords for OR-matching.
+ *
+ * @param query - User's original query
+ * @returns Object with original query and extracted keywords
+ */
+export function expandQueryForFts(query) {
+    const original = query.trim();
+    const keywords = extractKeywords(original);
+    // Build expanded query: original terms OR extracted keywords
+    // This ensures both exact matches and keyword matches are found
+    const expanded = keywords.length > 0 ? `${original} OR ${keywords.join(" OR ")}` : original;
+    return { original, keywords, expanded };
+}
+/**
+ * Expand query with optional LLM assistance.
+ * Falls back to local extraction if LLM is unavailable or fails.
+ */
+export async function expandQueryWithLlm(query, llmExpander) {
+    // If LLM expander is provided, try it first
+    if (llmExpander) {
+        try {
+            const llmKeywords = await llmExpander(query);
+            if (llmKeywords.length > 0) {
+                return llmKeywords;
+            }
+        }
+        catch {
+            // LLM failed, fall back to local extraction
+        }
+    }
+    // Fall back to local keyword extraction
+    return extractKeywords(query);
+}

package/dist/memory/temporal-decay.js

@@ -0,0 +1,119 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export const DEFAULT_TEMPORAL_DECAY_CONFIG = {
+    enabled: false,
+    halfLifeDays: 30,
+};
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DATED_MEMORY_PATH_RE = /(?:^|\/)memory\/(\d{4})-(\d{2})-(\d{2})\.md$/;
+export function toDecayLambda(halfLifeDays) {
+    if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0) {
+        return 0;
+    }
+    return Math.LN2 / halfLifeDays;
+}
+export function calculateTemporalDecayMultiplier(params) {
+    const lambda = toDecayLambda(params.halfLifeDays);
+    const clampedAge = Math.max(0, params.ageInDays);
+    if (lambda <= 0 || !Number.isFinite(clampedAge)) {
+        return 1;
+    }
+    return Math.exp(-lambda * clampedAge);
+}
+export function applyTemporalDecayToScore(params) {
+    return params.score * calculateTemporalDecayMultiplier(params);
+}
+function parseMemoryDateFromPath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/").replace(/^\.\//, "");
+    const match = DATED_MEMORY_PATH_RE.exec(normalized);
+    if (!match) {
+        return null;
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) {
+        return null;
+    }
+    const timestamp = Date.UTC(year, month - 1, day);
+    const parsed = new Date(timestamp);
+    if (parsed.getUTCFullYear() !== year ||
+        parsed.getUTCMonth() !== month - 1 ||
+        parsed.getUTCDate() !== day) {
+        return null;
+    }
+    return parsed;
+}
+function isEvergreenMemoryPath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/").replace(/^\.\//, "");
+    if (normalized === "MEMORY.md" || normalized === "memory.md") {
+        return true;
+    }
+    if (!normalized.startsWith("memory/")) {
+        return false;
+    }
+    return !DATED_MEMORY_PATH_RE.test(normalized);
+}
+async function extractTimestamp(params) {
+    const fromPath = parseMemoryDateFromPath(params.filePath);
+    if (fromPath) {
+        return fromPath;
+    }
+    // Memory root/topic files are evergreen knowledge and should not decay.
+    if (params.source === "memory" && isEvergreenMemoryPath(params.filePath)) {
+        return null;
+    }
+    if (!params.workspaceDir) {
+        return null;
+    }
+    const absolutePath = path.isAbsolute(params.filePath)
+        ? params.filePath
+        : path.resolve(params.workspaceDir, params.filePath);
+    try {
+        const stat = await fs.stat(absolutePath);
+        if (!Number.isFinite(stat.mtimeMs)) {
+            return null;
+        }
+        return new Date(stat.mtimeMs);
+    }
+    catch {
+        return null;
+    }
+}
+function ageInDaysFromTimestamp(timestamp, nowMs) {
+    const ageMs = Math.max(0, nowMs - timestamp.getTime());
+    return ageMs / DAY_MS;
+}
+export async function applyTemporalDecayToHybridResults(params) {
+    const config = { ...DEFAULT_TEMPORAL_DECAY_CONFIG, ...params.temporalDecay };
+    if (!config.enabled) {
+        return [...params.results];
+    }
+    const nowMs = params.nowMs ?? Date.now();
+    const timestampPromiseCache = new Map();
+    return Promise.all(params.results.map(async (entry) => {
+        const cacheKey = `${entry.source}:${entry.path}`;
+        let timestampPromise = timestampPromiseCache.get(cacheKey);
+        if (!timestampPromise) {
+            timestampPromise = extractTimestamp({
+                filePath: entry.path,
+                source: entry.source,
+                workspaceDir: params.workspaceDir,
+            });
+            timestampPromiseCache.set(cacheKey, timestampPromise);
+        }
+        const timestamp = await timestampPromise;
+        if (!timestamp) {
+            return entry;
+        }
+        const decayedScore = applyTemporalDecayToScore({
+            score: entry.score,
+            ageInDays: ageInDaysFromTimestamp(timestamp, nowMs),
+            halfLifeDays: config.halfLifeDays,
+        });
+        return {
+            ...entry,
+            score: decayedScore,
+        };
+    }));
+}

package/dist/process/kill-tree.js

@@ -0,0 +1,98 @@
+import { spawn } from "node:child_process";
+const DEFAULT_GRACE_MS = 3000;
+const MAX_GRACE_MS = 60_000;
+/**
+ * Best-effort process-tree termination with graceful shutdown.
+ * - Windows: use taskkill /T to include descendants. Sends SIGTERM-equivalent
+ *   first (without /F), then force-kills if process survives.
+ * - Unix: send SIGTERM to process group first, wait grace period, then SIGKILL.
+ *
+ * This gives child processes a chance to clean up (close connections, remove
+ * temp files, terminate their own children) before being hard-killed.
+ */
+export function killProcessTree(pid, opts) {
+    if (!Number.isFinite(pid) || pid <= 0) {
+        return;
+    }
+    const graceMs = normalizeGraceMs(opts?.graceMs);
+    if (process.platform === "win32") {
+        killProcessTreeWindows(pid, graceMs);
+        return;
+    }
+    killProcessTreeUnix(pid, graceMs);
+}
+function normalizeGraceMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_GRACE_MS;
+    }
+    return Math.max(0, Math.min(MAX_GRACE_MS, Math.floor(value)));
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function killProcessTreeUnix(pid, graceMs) {
+    // Step 1: Try graceful SIGTERM to process group
+    try {
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        // Process group doesn't exist or we lack permission - try direct
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch {
+            // Already gone
+            return;
+        }
+    }
+    // Step 2: Wait grace period, then SIGKILL if still alive
+    setTimeout(() => {
+        if (isProcessAlive(-pid)) {
+            try {
+                process.kill(-pid, "SIGKILL");
+                return;
+            }
+            catch {
+                // Fall through to direct pid kill
+            }
+        }
+        if (!isProcessAlive(pid)) {
+            return;
+        }
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // Process exited between liveness check and kill
+        }
+    }, graceMs).unref(); // Don't block event loop exit
+}
+function runTaskkill(args) {
+    try {
+        spawn("taskkill", args, {
+            stdio: "ignore",
+            detached: true,
+        });
+    }
+    catch {
+        // Ignore taskkill spawn failures
+    }
+}
+function killProcessTreeWindows(pid, graceMs) {
+    // Step 1: Try graceful termination (taskkill without /F)
+    runTaskkill(["/T", "/PID", String(pid)]);
+    // Step 2: Wait grace period, then force kill only if pid still exists.
+    // This avoids unconditional delayed /F kills after graceful shutdown.
+    setTimeout(() => {
+        if (!isProcessAlive(pid)) {
+            return;
+        }
+        runTaskkill(["/F", "/T", "/PID", String(pid)]);
+    }, graceMs).unref(); // Don't block event loop exit
+}