byterover-cli 2.0.0 → 2.1.0

package/dist/agent/infra/map/context-tree-store.js

@@ -0,0 +1,278 @@
+/**
+ * Context Tree Store.
+ *
+ * In-memory store implementing bounded buffer with automatic compaction.
+ * Two-tier architecture: synchronous buffering with bounded eviction + async final compaction.
+ *
+ * Hot path (store): synchronous, no LLM calls. If buffer exceeds τ_hard,
+ * entries are evicted, summaries consolidated, and single summaries truncated
+ * via deterministic truncation in a loop until totalTokens ≤ τ_hard or no
+ * further reduction is possible (single entry with no summary).
+ *
+ * Cold path (compact): called ONCE after worker pool completes.
+ * Runs full 3-level escalation to produce high-quality summary.
+ *
+ * Memory bound: after store() completes, totalTokens ≤ τ_hard + maxSingleLabeledEntrySize
+ * where labeled entry size = countTokens("[Item N]: content").
+ * The single-entry overshoot covers the item that triggered eviction.
+ */
+import { randomUUID } from 'node:crypto';
+import { buildDeterministicFallbackCompaction, isCompactionOutputValid, withAggressiveCompactionDirective, } from '../../../shared/utils/escalation-utils.js';
+const SUMMARY_PROMPT = `Summarize the following map processing results concisely, preserving:
+- Key findings and patterns across items
+- Important values, counts, and statistics
+- Any errors or anomalies worth noting
+- Actionable insights for the next processing step
+
+Keep the summary focused and information-dense.
+
+Results:
+`;
+/**
+ * Context Tree Store with bounded buffer and 3-level compaction.
+ */
+export class ContextTreeStore {
+    entries = new Map();
+    generator;
+    maxCompactionRounds;
+    summaries = [];
+    summaryBudget;
+    summaryHandle;
+    summaryTokens = 0;
+    tauHard;
+    tokenizer;
+    totalTokens = 0;
+    constructor(options) {
+        this.generator = options.generator;
+        this.tokenizer = options.tokenizer;
+        this.tauHard = options.tauHard;
+        this.summaryBudget = options.summaryBudget ?? 2000;
+        this.maxCompactionRounds = options.maxCompactionRounds ?? 10;
+    }
+    /**
+     * Canonical entry format — single source of truth for labeled entries.
+     * Used in store(), evictOldest(), and compact().
+     */
+    static formatEntry(index, content) {
+        return `[Item ${index}]: ${content}`;
+    }
+    /**
+     * Cold path — called ONCE after worker pool completes.
+     * Runs full 3-level escalation (may involve LLM calls) to produce
+     * high-quality summary from remaining entries + prior summaries.
+     */
+    async compact() {
+        // Join all summaries + remaining entries into source text
+        const parts = [...this.summaries];
+        const sortedEntries = [...this.entries.entries()].sort(([a], [b]) => a - b);
+        for (const [index, entry] of sortedEntries) {
+            parts.push(ContextTreeStore.formatEntry(index, entry.content));
+        }
+        const sourceText = parts.join('\n');
+        if (!sourceText.trim()) {
+            return;
+        }
+        const inputTokens = this.tokenizer.countTokens(sourceText);
+        // If already within budget, use directly
+        if (inputTokens <= this.summaryBudget) {
+            this.summaryHandle = sourceText;
+            return;
+        }
+        // Level 1: Normal LLM summarization
+        const level1 = await this.tryLlmSummarization(sourceText, false);
+        if (level1 && this.tokenizer.countTokens(level1) <= this.summaryBudget) {
+            this.summaryHandle = level1;
+            return;
+        }
+        // Level 2: Aggressive LLM summarization
+        const level2 = await this.tryLlmSummarization(sourceText, true);
+        if (level2 && this.tokenizer.countTokens(level2) <= this.summaryBudget) {
+            this.summaryHandle = level2;
+            return;
+        }
+        // Level 3: Deterministic truncation to fit within summaryBudget
+        this.summaryHandle = buildDeterministicFallbackCompaction({
+            inputTokens: this.summaryBudget,
+            sourceText: level2 ?? level1 ?? sourceText,
+            suffixLabel: 'context-tree-compact',
+            tokenizer: this.tokenizer,
+        });
+    }
+    /**
+     * Returns compact summary text, bounded to summaryBudget tokens.
+     * Must call compact() first for LLM-quality output.
+     */
+    getSummaryHandle() {
+        return this.summaryHandle;
+    }
+    /**
+     * Hot path — called from processItem(). Synchronous, no LLM calls.
+     * If buffer exceeds τ_hard, evicts entries and consolidates summaries
+     * until totalTokens ≤ τ_hard or no further reduction is possible.
+     */
+    store(index, content) {
+        const tokens = this.tokenizer.countTokens(ContextTreeStore.formatEntry(index, content));
+        // Handle index overwrite — subtract old tokens before adding new
+        const existing = this.entries.get(index);
+        if (existing) {
+            this.totalTokens -= existing.tokens;
+        }
+        this.entries.set(index, { content, tokens });
+        this.totalTokens += tokens;
+        // Eviction loop: keep reducing until within budget or stuck
+        let rounds = 0;
+        while (this.totalTokens > this.tauHard && rounds < this.maxCompactionRounds) {
+            const before = this.totalTokens;
+            if (this.entries.size > 1) {
+                this.evictOldest();
+            }
+            else if (this.summaries.length > 1) {
+                this.consolidateSummaries();
+            }
+            else if (this.summaries.length === 1 && this.summaryTokens > 0) {
+                this.truncateSingleSummary();
+            }
+            else {
+                break; // Single entry + no summaries — can't reduce further
+            }
+            // Guard: if eviction didn't reduce tokens, stop to prevent infinite loop
+            if (this.totalTokens >= before) {
+                break;
+            }
+            rounds++;
+        }
+    }
+    /**
+     * Consolidate all summaries into a single truncated summary.
+     * Called when entries alone can't bring totalTokens below τ_hard.
+     * Synchronous — uses deterministic truncation only.
+     */
+    consolidateSummaries() {
+        if (this.summaries.length <= 1) {
+            return;
+        }
+        const sourceText = this.summaries.join('\n');
+        const oldSummaryTokens = this.summaryTokens;
+        // Deterministic truncation to half of current summary size
+        const targetTokens = Math.max(1, Math.floor(oldSummaryTokens / 2));
+        const consolidated = buildDeterministicFallbackCompaction({
+            inputTokens: targetTokens,
+            sourceText,
+            suffixLabel: 'context-tree-consolidation',
+            tokenizer: this.tokenizer,
+        });
+        // Replace all summaries with single consolidated one
+        this.summaries.length = 0;
+        this.summaryTokens = 0;
+        this.totalTokens -= oldSummaryTokens;
+        if (consolidated) {
+            const tokens = this.tokenizer.countTokens(consolidated);
+            this.summaries.push(consolidated);
+            this.summaryTokens = tokens;
+            this.totalTokens += tokens;
+        }
+    }
+    /**
+     * Synchronous eviction of oldest entries via deterministic truncation.
+     * Truncates oldest half of entries into a compact summary chunk.
+     */
+    evictOldest() {
+        const sortedKeys = [...this.entries.keys()].sort((a, b) => a - b);
+        const evictCount = Math.max(1, Math.floor(sortedKeys.length / 2));
+        const keysToEvict = sortedKeys.slice(0, evictCount);
+        // Build source text from entries to evict
+        const parts = [];
+        let evictedTokens = 0;
+        for (const key of keysToEvict) {
+            const entry = this.entries.get(key);
+            parts.push(ContextTreeStore.formatEntry(key, entry.content));
+            evictedTokens += entry.tokens;
+        }
+        const sourceText = parts.join('\n');
+        // Target = evicted canonical budget (NOT countTokens(sourceText))
+        // Since entry.tokens now counts the labeled form, evictedTokens ≈ countTokens(sourceText)
+        // minus \n joiners. The binary search guarantees countTokens(summary) < evictedTokens.
+        const summary = buildDeterministicFallbackCompaction({
+            inputTokens: evictedTokens,
+            sourceText,
+            suffixLabel: 'context-tree-eviction',
+            tokenizer: this.tokenizer,
+        });
+        // Remove evicted entries
+        for (const key of keysToEvict) {
+            this.entries.delete(key);
+        }
+        this.totalTokens -= evictedTokens;
+        // Store summary chunk — hard safety: drop if not strictly smaller than evicted budget
+        if (summary) {
+            const summaryTokens = this.tokenizer.countTokens(summary);
+            if (summaryTokens < evictedTokens) {
+                this.summaries.push(summary);
+                this.summaryTokens += summaryTokens;
+                this.totalTokens += summaryTokens;
+            }
+            // else: drop summary entirely — eviction is still strictly reducing
+        }
+    }
+    /**
+     * Truncate a single remaining summary to fit within budget.
+     * Called when entries.size <= 1 and summaries.length === 1 but still over τ_hard.
+     * Halves the summary via deterministic truncation each round.
+     */
+    truncateSingleSummary() {
+        if (this.summaries.length !== 1 || this.summaryTokens === 0) {
+            return;
+        }
+        const sourceText = this.summaries[0];
+        const oldTokens = this.summaryTokens;
+        // Target: budget minus current entry tokens, or half of summary — whichever is smaller
+        const entryTokens = this.totalTokens - this.summaryTokens;
+        const budgetTarget = Math.max(1, this.tauHard - entryTokens);
+        const halfTarget = Math.max(1, Math.floor(oldTokens / 2));
+        const targetTokens = Math.min(budgetTarget, halfTarget);
+        const truncated = buildDeterministicFallbackCompaction({
+            inputTokens: targetTokens,
+            sourceText,
+            suffixLabel: 'context-tree-single-truncation',
+            tokenizer: this.tokenizer,
+        });
+        // Replace summary
+        this.summaries.length = 0;
+        this.summaryTokens = 0;
+        this.totalTokens -= oldTokens;
+        if (truncated) {
+            const tokens = this.tokenizer.countTokens(truncated);
+            this.summaries.push(truncated);
+            this.summaryTokens = tokens;
+            this.totalTokens += tokens;
+        }
+    }
+    /**
+     * Attempt LLM summarization for compact().
+     */
+    async tryLlmSummarization(sourceText, aggressive) {
+        try {
+            const prompt = aggressive
+                ? withAggressiveCompactionDirective(SUMMARY_PROMPT + sourceText)
+                : SUMMARY_PROMPT + sourceText;
+            const maxTokens = aggressive
+                ? Math.floor(0.6 * this.summaryBudget)
+                : this.summaryBudget;
+            const response = await this.generator.generateContent({
+                config: { maxTokens, temperature: 0 },
+                contents: [{ content: prompt, role: 'user' }],
+                model: 'default',
+                systemPrompt: 'You are a data summarizer. Produce concise, information-dense summaries of map processing results.',
+                taskId: randomUUID(),
+            });
+            const result = response.content;
+            if (result && isCompactionOutputValid(result)) {
+                return result;
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}

package/dist/agent/infra/map/index.d.ts

@@ -0,0 +1,4 @@
+export { type AgenticMapServiceOptions, executeAgenticMap } from './agentic-map-service.js';
+export { executeLlmMap, type LlmMapServiceOptions } from './llm-map-service.js';
+export { type AgenticMapParameters, AgenticMapParametersSchema, buildAgenticMapSystemMessage, buildRetryMessage, buildUserMessage, itemsToJsonl, LLM_MAP_SYSTEM_MESSAGE, type LlmMapParameters, LlmMapParametersSchema, parseJsonlFile, stableStringify, validateAgainstSchema, } from './map-shared.js';
+export { type InMemoryMapRunResult, type MapProgress, type MapRunResult, runMapWorkerPool, type WorkerPoolOptions } from './worker-pool.js';

package/dist/agent/infra/map/index.js

@@ -0,0 +1,4 @@
+export { executeAgenticMap } from './agentic-map-service.js';
+export { executeLlmMap } from './llm-map-service.js';
+export { AgenticMapParametersSchema, buildAgenticMapSystemMessage, buildRetryMessage, buildUserMessage, itemsToJsonl, LLM_MAP_SYSTEM_MESSAGE, LlmMapParametersSchema, parseJsonlFile, stableStringify, validateAgainstSchema, } from './map-shared.js';
+export { runMapWorkerPool } from './worker-pool.js';

package/dist/agent/infra/map/llm-map-memory.d.ts

@@ -0,0 +1,59 @@
+/**
+ * In-Memory LLM Map — parallel, stateless LLM calls over in-memory items.
+ *
+ * Reuses `runMapWorkerPool` and the `callLlm`/`withTimeout` pattern from
+ * `llm-map-service.ts`, but skips all JSONL file I/O.
+ *
+ * Designed for curation extraction: processes text chunks in parallel,
+ * returns CurationFact[] per item with fixed internal validation
+ * (no generic schema — curation-specific).
+ */
+import type { IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+import type { ILogger } from '../../core/interfaces/i-logger.js';
+import type { ContextTreeStore } from './context-tree-store.js';
+import { type CurationFact } from '../sandbox/curation-helpers.js';
+import { type MapProgress } from './worker-pool.js';
+export interface LlmMapMemoryOptions {
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Number of parallel workers (default: 8) */
+    concurrency?: number;
+    /** Optional context tree store for result aggregation */
+    contextTreeStore?: ContextTreeStore;
+    /** Content generator for stateless LLM calls */
+    generator: IContentGenerator;
+    /** Items to process (in-memory, not from JSONL) */
+    items: unknown[];
+    /** Optional logger for fail-open warnings */
+    logger?: ILogger;
+    /** Max attempts per item (default: 3) */
+    maxAttempts?: number;
+    /** Progress callback */
+    onProgress?: (progress: MapProgress) => void;
+    /** Prompt template for each item */
+    prompt: string;
+    /** Task ID for billing */
+    taskId?: string;
+    /** Timeout per item in seconds (default: 120) */
+    timeoutSeconds?: number;
+}
+export interface LlmMapMemoryResult {
+    /** Number of failed items */
+    failed: number;
+    /** Per-item results (ordered by input index). null for failed items. */
+    results: (CurationFact[] | null)[];
+    /** Number of succeeded items */
+    succeeded: number;
+    /** Compact summary of processed items (from ContextTreeStore) */
+    summaryHandle?: string;
+    /** Total items processed */
+    total: number;
+}
+/**
+ * Execute an in-memory LLM map for curation extraction.
+ *
+ * Processes items in parallel using `runMapWorkerPool`. Each item gets a
+ * stateless LLM call that must return CurationFact[]. Invalid categories
+ * are normalized to undefined. Single-object responses are wrapped in arrays.
+ */
+export declare function executeLlmMapMemory(options: LlmMapMemoryOptions): Promise<LlmMapMemoryResult>;

package/dist/agent/infra/map/llm-map-memory.js

@@ -0,0 +1,187 @@
+/**
+ * In-Memory LLM Map — parallel, stateless LLM calls over in-memory items.
+ *
+ * Reuses `runMapWorkerPool` and the `callLlm`/`withTimeout` pattern from
+ * `llm-map-service.ts`, but skips all JSONL file I/O.
+ *
+ * Designed for curation extraction: processes text chunks in parallel,
+ * returns CurationFact[] per item with fixed internal validation
+ * (no generic schema — curation-specific).
+ */
+import { VALID_CATEGORIES } from '../sandbox/curation-helpers.js';
+import { buildRetryMessage, buildUserMessage, callLlm, withTimeout, } from './map-shared.js';
+import { runMapWorkerPool } from './worker-pool.js';
+// ── Fixed output schema for curation facts ───────────────────────────────────
+const CURATION_FACT_SCHEMA = {
+    items: {
+        properties: {
+            category: { type: 'string' },
+            statement: { type: 'string' },
+            subject: { type: 'string' },
+        },
+        required: ['statement'],
+        type: 'object',
+    },
+    type: 'array',
+};
+// ── Main Function ────────────────────────────────────────────────────────────
+/**
+ * Execute an in-memory LLM map for curation extraction.
+ *
+ * Processes items in parallel using `runMapWorkerPool`. Each item gets a
+ * stateless LLM call that must return CurationFact[]. Invalid categories
+ * are normalized to undefined. Single-object responses are wrapped in arrays.
+ */
+export async function executeLlmMapMemory(options) {
+    const { abortSignal, concurrency = 8, generator, items, maxAttempts = 3, onProgress, prompt, taskId, timeoutSeconds = 120, } = options;
+    if (items.length === 0) {
+        return { failed: 0, results: [], succeeded: 0, total: 0 };
+    }
+    const runStartedAt = new Date().toISOString();
+    async function processItem(itemIndex, item) {
+        const userMessage = buildUserMessage(prompt, 'memory', runStartedAt, itemIndex, item, CURATION_FACT_SCHEMA);
+        // Per-item timeout
+        const timeoutController = new AbortController();
+        const timeoutHandle = setTimeout(() => {
+            timeoutController.abort();
+        }, timeoutSeconds * 1000);
+        try {
+            let attemptsUsed = 1;
+            let lastError = '';
+            let lastResponse = '';
+            // Initial LLM call (stateless — no tool access)
+            const response = await withTimeout(callLlm(generator, userMessage, taskId, abortSignal), timeoutController.signal);
+            lastResponse = response.content;
+            // Validation loop with retry
+            while (true) {
+                const validated = validateAndNormalize(lastResponse);
+                if (validated.valid) {
+                    // Fail-open: store result in context tree if available
+                    if (options.contextTreeStore) {
+                        try {
+                            options.contextTreeStore.store(itemIndex, JSON.stringify(validated.facts));
+                        }
+                        catch (storeError) {
+                            options.logger?.warn('Context tree store failed', { error: String(storeError), itemIndex });
+                        }
+                    }
+                    return validated.facts;
+                }
+                lastError = validated.error;
+                // Check retry budget
+                if (attemptsUsed >= maxAttempts) {
+                    throw new Error(`Failed after ${attemptsUsed} attempts. Last error: ${lastError}`);
+                }
+                // Check abort or timeout
+                if (abortSignal?.aborted || timeoutController.signal.aborted) {
+                    throw new Error('Aborted or timed out');
+                }
+                // Retry with error context + prior response
+                attemptsUsed++;
+                const retryMessage = buildRetryMessage(userMessage, lastError, lastResponse);
+                // eslint-disable-next-line no-await-in-loop
+                const retryResponse = await withTimeout(callLlm(generator, retryMessage, taskId, abortSignal), timeoutController.signal);
+                lastResponse = retryResponse.content;
+            }
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+        }
+    }
+    // Run in-memory worker pool
+    const result = await runMapWorkerPool({
+        abortSignal,
+        concurrency,
+        items,
+        onProgress,
+        processItem,
+    });
+    // Compact context tree and attach summaryHandle (fail-open)
+    if (options.contextTreeStore) {
+        try {
+            await options.contextTreeStore.compact();
+            result.summaryHandle = options.contextTreeStore.getSummaryHandle();
+        }
+        catch (compactError) {
+            options.logger?.warn('Context tree compaction failed', { error: String(compactError) });
+        }
+    }
+    // Convert Map<number, unknown> to ordered array with nulls for failures
+    const ordered = [];
+    for (let i = 0; i < items.length; i++) {
+        const value = result.results.get(i);
+        ordered.push(value ? value : null);
+    }
+    return {
+        failed: result.failed,
+        results: ordered,
+        succeeded: result.succeeded,
+        summaryHandle: result.summaryHandle,
+        total: result.total,
+    };
+}
+// ── Internal Helpers ─────────────────────────────────────────────────────────
+/**
+ * Validate and normalize LLM response into CurationFact[].
+ *
+ * Single normalization layer:
+ * - Accepts both CurationFact and CurationFact[] (wraps single objects)
+ * - Validates each fact has typeof statement === 'string' && statement.trim().length > 0
+ * - Normalizes invalid categories to undefined
+ */
+function validateAndNormalize(response) {
+    let parsed;
+    try {
+        parsed = JSON.parse(response);
+    }
+    catch (error) {
+        return {
+            error: `JSON parse error: ${error instanceof Error ? error.message : String(error)}`,
+            facts: [],
+            valid: false,
+        };
+    }
+    // Normalize single object to array
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) && 'statement' in parsed) {
+        parsed = [parsed];
+    }
+    if (!Array.isArray(parsed)) {
+        return {
+            error: 'Expected array of facts or a single fact object with "statement" field',
+            facts: [],
+            valid: false,
+        };
+    }
+    const facts = [];
+    for (const item of parsed) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const { category, statement, subject } = item;
+        if (typeof statement !== 'string' || statement.trim().length === 0)
+            continue;
+        facts.push({
+            category: normalizeCategory(category),
+            statement: statement.trim(),
+            subject: typeof subject === 'string' ? subject.trim() : undefined,
+        });
+    }
+    // Empty input array [] is valid — some chunks legitimately contain no extractable facts.
+    // But if the LLM returned items and ALL were malformed, that's a format error worth retrying.
+    if (facts.length === 0 && parsed.length > 0) {
+        return {
+            error: `All ${parsed.length} items were malformed. Each fact must have a non-empty "statement" string.`,
+            facts: [],
+            valid: false,
+        };
+    }
+    return { error: '', facts, valid: true };
+}
+/**
+ * Normalize category to valid CurationCategory or undefined.
+ */
+function normalizeCategory(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const lower = value.toLowerCase().trim();
+    return VALID_CATEGORIES.has(lower) ? lower : undefined;
+}

package/dist/agent/infra/map/llm-map-service.d.ts

@@ -0,0 +1,36 @@
+import type { IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+import type { ILogger } from '../../core/interfaces/i-logger.js';
+import type { ContextTreeStore } from './context-tree-store.js';
+import { type LlmMapParameters } from './map-shared.js';
+import { type MapProgress, type MapRunResult } from './worker-pool.js';
+export interface LlmMapServiceOptions {
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Optional context tree store for result aggregation */
+    contextTreeStore?: ContextTreeStore;
+    /** Content generator (LLM backend) for making stateless calls */
+    generator: IContentGenerator;
+    /** Optional logger for fail-open warnings */
+    logger?: ILogger;
+    /** Progress callback */
+    onProgress?: (progress: MapProgress) => void;
+    /** Tool parameters from the LLM */
+    params: LlmMapParameters;
+    /** Task ID for billing tracking */
+    taskId?: string;
+    /** Working directory (project root) */
+    workingDirectory: string;
+}
+/**
+ * Execute an LLM-Map: parallel, stateless LLM calls over a JSONL file.
+ *
+ * For each item (line), makes a single LLM API call (no tools, no file I/O)
+ * that must return one JSON value conforming to the provided output schema.
+ * If validation fails, the system retries with the error and prior response.
+ *
+ * Ported from VoltCode's llm-map.ts, adapted for byterover-cli:
+ * - Uses IContentGenerator instead of AI SDK's generateText()
+ * - Uses in-memory worker pool (no FileMapStore / PostgreSQL)
+ * - Runs in-process (no SQS)
+ */
+export declare function executeLlmMap(options: LlmMapServiceOptions): Promise<MapRunResult>;