byterover-cli 1.8.0 → 2.1.0

package/dist/server/infra/executor/curate-executor.js

@@ -2,6 +2,11 @@ import path from 'node:path';
 import { FileValidationError } from '../../core/domain/errors/task-error.js';
 import { createFileContentReader, } from '../../utils/file-content-reader.js';
 import { validateFileForCurate } from '../../utils/file-validator.js';
+import { FileContextTreeManifestService } from '../context-tree/file-context-tree-manifest-service.js';
+import { FileContextTreeSnapshotService } from '../context-tree/file-context-tree-snapshot-service.js';
+import { FileContextTreeSummaryService } from '../context-tree/file-context-tree-summary-service.js';
+import { diffStates } from '../context-tree/snapshot-diff.js';
+import { PreCompactionService } from './pre-compaction/pre-compaction-service.js';
 /**
  * CurateExecutor - Executes curate tasks with an injected CipherAgent.
  *
@@ -9,8 +14,8 @@ import { validateFileForCurate } from '../../utils/file-validator.js';
  * It's an Executor that wraps agent.execute() with curate-specific options.
  *
  * Architecture:
- * - TaskProcessor injects the long-lived CipherAgent
- * - Event streaming is handled by agent-worker (subscribes to agentEventBus)
+ * - AgentProcess injects the long-lived CipherAgent
+ * - Event streaming is handled by agent-process (subscribes to agentEventBus)
  * - Transport handles task lifecycle (task:started, task:completed, task:error)
  * - Executor focuses solely on curate execution
  */
@@ -23,24 +28,108 @@ export class CurateExecutor {
     static MAX_LINES_PER_FILE = 2000;
     /** Maximum pages to extract for PDFs */
     static MAX_PDF_PAGES = 50;
+    /** Last curation status — available for future status-check command */
+    lastStatus;
     fileContentReader;
+    preCompactionService = new PreCompactionService();
     constructor(fileContentReader) {
         this.fileContentReader = fileContentReader ?? createFileContentReader();
     }
     async executeWithAgent(agent, options) {
         const { clientCwd, content, files, taskId } = options;
-        // Process file references - now reads file contents directly
+        // --- Phase 1: Preprocessing (no sessions created yet — safe to throw) ---
         const fileReferenceInstructions = await this.processFileReferences(files ?? [], clientCwd);
-        // Build prompt with optional file reference instructions
-        const prompt = fileReferenceInstructions ? `${content}\n${fileReferenceInstructions}` : content;
-        // Execute with curate commandType
-        // Agent uses its default session (created during start())
-        // Task lifecycle is managed by Transport (task:started, task:completed, task:error)
-        const response = await agent.execute(prompt, {
-            executionContext: { commandType: 'curate' },
-            taskId,
-        });
-        return response;
+        const fullContext = fileReferenceInstructions ? `${content}\n${fileReferenceInstructions}` : content;
+        // --- Phase 2: Pre-compaction (fail-open, manages its own session lifecycle) ---
+        const compactionResult = await this.preCompactionService.compact(agent, fullContext, taskId);
+        const effectiveContext = compactionResult.context;
+        // --- Phase 3: Curation (session created AFTER preprocessing + compaction) ---
+        // Capture pre-curation state for snapshot diff (summary propagation)
+        const baseDir = clientCwd ?? process.cwd();
+        const snapshotService = new FileContextTreeSnapshotService({ baseDirectory: baseDir });
+        let preState;
+        try {
+            preState = await snapshotService.getCurrentState(baseDir);
+        }
+        catch {
+            // Fail-open: if snapshot fails, skip summary propagation
+        }
+        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true });
+        try {
+            // Task-scoped variable names for RLM pattern.
+            // Replace hyphens with underscores: UUIDs have hyphens which are invalid in JS identifiers,
+            // so the LLM would naturally use underscores when writing code-exec calls — causing a
+            // ReferenceError if the variable was stored under the hyphen version.
+            const taskIdSafe = taskId.replaceAll('-', '_');
+            const ctxVar = `__curate_ctx_${taskIdSafe}`;
+            const histVar = `__curate_hist_${taskIdSafe}`;
+            const metaVar = `__curate_meta_${taskIdSafe}`;
+            // Compute context metadata (RLM pattern — LM sees metadata, not raw content)
+            const contextLines = effectiveContext.split('\n');
+            const metadata = {
+                charCount: effectiveContext.length,
+                lineCount: contextLines.length,
+                messageCount: (effectiveContext.match(/\n\n\[(USER|ASSISTANT)\]:/g) || []).length,
+                ...(compactionResult.preCompacted && {
+                    originalCharCount: compactionResult.originalCharCount,
+                    preCompacted: true,
+                    preCompactionTier: compactionResult.preCompactionTier,
+                }),
+                preview: effectiveContext.slice(0, 500),
+                type: 'string',
+            };
+            // Inject context, metadata, empty history, and taskId into the TASK session's sandbox
+            const taskIdVar = `__taskId_${taskIdSafe}`;
+            agent.setSandboxVariableOnSession(taskSessionId, ctxVar, effectiveContext);
+            agent.setSandboxVariableOnSession(taskSessionId, histVar, { entries: [], totalProcessed: 0 });
+            agent.setSandboxVariableOnSession(taskSessionId, metaVar, metadata);
+            agent.setSandboxVariableOnSession(taskSessionId, taskIdVar, taskId);
+            // Prompt with curation helpers guidance (tools.curation.* replaces manual infrastructure code)
+            const prompt = [
+                `Curate using RLM approach.`,
+                `Context variable: ${ctxVar} (${metadata.charCount} chars, ${metadata.lineCount} lines, ${metadata.messageCount} messages)`,
+                `History variable: ${histVar}`,
+                `Metadata variable: ${metaVar}`,
+                `Task ID variable: ${taskIdVar} (pass as bare variable, not a string)`,
+                `IMPORTANT: Do NOT print raw context. Start with tools.curation.recon(${ctxVar}, ${metaVar}, ${histVar}) to assess.`,
+                `For chunked extraction use tools.curation.mapExtract(). Pass taskId: ${taskIdVar} (bare variable).`,
+                `IMPORTANT: Any code_exec call containing mapExtract MUST use timeout: 300000 on the code_exec tool call itself (not inside mapExtract options).`,
+                `Use tools.curation.groupBySubject() and tools.curation.dedup() to organize extractions.`,
+                `Verify via result.applied[].filePath — do NOT call readFile for verification.`,
+            ].join('\n');
+            // Execute on the task session (isolated sandbox + history)
+            // Task lifecycle is managed by Transport (task:started, task:completed, task:error)
+            const response = await agent.executeOnSession(taskSessionId, prompt, {
+                executionContext: { clearHistory: true, commandType: 'curate', maxIterations: 50 },
+                taskId,
+            });
+            // Parse curation status from agent response for status tracking
+            this.lastStatus = this.parseCurationStatus(taskId, response);
+            // --- Phase 4: Post-curation summary propagation (fail-open) ---
+            if (preState) {
+                try {
+                    const postState = await snapshotService.getCurrentState(baseDir);
+                    const changedPaths = diffStates(preState, postState);
+                    if (changedPaths.length > 0) {
+                        const summaryService = new FileContextTreeSummaryService();
+                        const results = await summaryService.propagateStaleness(changedPaths, agent, baseDir);
+                        // Opportunistic manifest rebuild (pre-warm for next query)
+                        if (results.some((r) => r.actionTaken)) {
+                            const manifestService = new FileContextTreeManifestService({ baseDirectory: baseDir });
+                            await manifestService.buildManifest(baseDir);
+                        }
+                    }
+                }
+                catch {
+                    // Fail-open: summary/manifest errors never block curation
+                }
+            }
+            return response;
+        }
+        finally {
+            // Clean up entire task session (sandbox + history) in one call
+            await agent.deleteTaskSession(taskSessionId);
+        }
     }
     /**
      * Format file contents for inclusion in the prompt.
@@ -83,6 +172,39 @@ export class CurateExecutor {
             }
         }
     }
+    /**
+     * Parse curation status from the agent response.
+     * Extracts JSON status block if present, otherwise infers from response text.
+     */
+    parseCurationStatus(taskId, response) {
+        const defaultSummary = { added: 0, deleted: 0, failed: 0, merged: 0, updated: 0 };
+        const defaultVerification = { checked: 0, confirmed: 0, missing: [] };
+        // Try to extract JSON status block from response (agent instructed to include it)
+        try {
+            const jsonMatch = /```json\n([\S\s]*?)\n```/.exec(response);
+            if (jsonMatch) {
+                const parsed = JSON.parse(jsonMatch[1]);
+                return {
+                    completedAt: new Date().toISOString(),
+                    status: parsed.summary?.failed > 0 ? 'partial' : 'success',
+                    summary: parsed.summary ?? defaultSummary,
+                    taskId,
+                    verification: parsed.verification ?? defaultVerification,
+                };
+            }
+        }
+        catch {
+            // Ignore parse errors — fall through to heuristic
+        }
+        // Fallback: infer from response text
+        return {
+            completedAt: new Date().toISOString(),
+            status: response.includes('failed') ? 'failed' : 'success',
+            summary: defaultSummary,
+            taskId,
+            verification: defaultVerification,
+        };
+    }
     /**
      * Process file paths from --files flag.
      * Now reads file contents directly using FileContentReader.

package/dist/server/infra/executor/direct-search-responder.d.ts

@@ -1,9 +1,9 @@
-/** Score at which the result is so strong that dominance check is skipped */
-export declare const DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD = 15;
-/** Minimum score for the top result to qualify for a direct (no-LLM) response */
-export declare const DIRECT_RESPONSE_SCORE_THRESHOLD = 8;
-/** Top result must be N times the second result's score to be considered dominant */
-export declare const DIRECT_RESPONSE_DOMINANCE_RATIO = 2;
+/** Normalized score at which the result is so strong that dominance check is skipped */
+export declare const DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD = 0.93;
+/** Minimum normalized score for the top result to qualify for a direct (no-LLM) response */
+export declare const DIRECT_RESPONSE_SCORE_THRESHOLD = 0.85;
+/** Minimum gap between top and second result's normalized score to be considered dominant */
+export declare const DIRECT_RESPONSE_MIN_GAP = 0.08;
 /**
  * A search result with full document content for direct response formatting.
  */
@@ -17,10 +17,13 @@ export interface DirectSearchResult {
  * Determines if search results are confident enough for a direct response
  * without involving the LLM.
  *
- * Requires:
+ * Uses normalized [0, 1) scores with a gap-based dominance model:
  * 1. Top result score >= DIRECT_RESPONSE_SCORE_THRESHOLD (minimum confidence)
  * 2. Either: top score >= HIGH_CONFIDENCE_THRESHOLD (strong enough to skip dominance check)
- *    Or: top result dominates other results (score >= 2x the second result)
+ *    Or: gap between top and #2 >= DIRECT_RESPONSE_MIN_GAP (clear separation)
+ *
+ * Gap-based instead of ratio-based because normalized scores cluster in [0.8, 0.95],
+ * making ratio checks (e.g., 2x) impossible to satisfy.
  *
  * @param results - Sorted search results (highest score first)
  * @returns true if a direct response can be served

package/dist/server/infra/executor/direct-search-responder.js

@@ -1,21 +1,24 @@
-/** Score at which the result is so strong that dominance check is skipped */
-export const DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD = 15;
-/** Minimum score for the top result to qualify for a direct (no-LLM) response */
-export const DIRECT_RESPONSE_SCORE_THRESHOLD = 8;
-/** Top result must be N times the second result's score to be considered dominant */
-export const DIRECT_RESPONSE_DOMINANCE_RATIO = 2;
+/** Normalized score at which the result is so strong that dominance check is skipped */
+export const DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD = 0.93;
+/** Minimum normalized score for the top result to qualify for a direct (no-LLM) response */
+export const DIRECT_RESPONSE_SCORE_THRESHOLD = 0.85;
+/** Minimum gap between top and second result's normalized score to be considered dominant */
+export const DIRECT_RESPONSE_MIN_GAP = 0.08;
 /** Maximum content length per document in the direct response */
-const MAX_CONTENT_LENGTH = 1500;
+const MAX_CONTENT_LENGTH = 5000;
 /** Maximum number of documents to include in the direct response */
-const MAX_DOCS = 3;
+const MAX_DOCS = 5;
 /**
  * Determines if search results are confident enough for a direct response
  * without involving the LLM.
  *
- * Requires:
+ * Uses normalized [0, 1) scores with a gap-based dominance model:
  * 1. Top result score >= DIRECT_RESPONSE_SCORE_THRESHOLD (minimum confidence)
  * 2. Either: top score >= HIGH_CONFIDENCE_THRESHOLD (strong enough to skip dominance check)
- *    Or: top result dominates other results (score >= 2x the second result)
+ *    Or: gap between top and #2 >= DIRECT_RESPONSE_MIN_GAP (clear separation)
+ *
+ * Gap-based instead of ratio-based because normalized scores cluster in [0.8, 0.95],
+ * making ratio checks (e.g., 2x) impossible to satisfy.
  *
  * @param results - Sorted search results (highest score first)
  * @returns true if a direct response can be served
@@ -32,10 +35,9 @@ export function canRespondDirectly(results) {
     // High-confidence path: score so strong that dominance is irrelevant
     if (topResult.score >= DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD)
         return true;
-    const secondScore = results[1].score;
-    if (secondScore === 0)
-        return true;
-    return topResult.score / secondScore >= DIRECT_RESPONSE_DOMINANCE_RATIO;
+    // Gap-based dominance: top must be clearly separated from #2
+    const gap = topResult.score - results[1].score;
+    return gap >= DIRECT_RESPONSE_MIN_GAP;
 }
 /**
  * Format a direct response from search results (no LLM involved).

package/dist/server/infra/executor/folder-pack-executor.js

@@ -1,5 +1,17 @@
+import { appendFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+const LOG_PATH = process.env.BRV_SESSION_LOG;
+function folderPackLog(message) {
+    if (!LOG_PATH)
+        return;
+    try {
+        appendFileSync(LOG_PATH, `${new Date().toISOString()} [folder-pack-executor] ${message}\n`);
+    }
+    catch {
+        // ignore — never block on logging
+    }
+}
 /**
  * FolderPackExecutor - Executes folder pack + curate tasks with an injected CipherAgent.
  *
@@ -23,6 +35,9 @@ export class FolderPackExecutor {
     }
     async executeWithAgent(agent, options) {
         const { clientCwd, content, folderPath, taskId } = options;
+        if (!folderPath) {
+            throw new Error('folderPath is required for curate-folder tasks');
+        }
         // Resolve folder path
         const basePath = clientCwd ?? process.cwd();
         const absoluteFolderPath = path.isAbsolute(folderPath) ? folderPath : path.resolve(basePath, folderPath);
@@ -35,7 +50,7 @@ export class FolderPackExecutor {
         // Use iterative extraction strategy (inspired by rlm)
         // Stores packed folder in sandbox environment and lets agent iteratively query/extract
         // This avoids token limits entirely - works for folders of any size
-        return this.executeIterative(agent, packResult, content, absoluteFolderPath, taskId);
+        return this.executeIterative(agent, packResult, content, absoluteFolderPath, taskId, basePath);
     }
     /**
      * Build iterative extraction prompt with file-based access.
@@ -468,7 +483,7 @@ When curating knowledge from source files, you MUST preserve the exact, complete
    - Detect: fenced blocks with mermaid/plantuml tags, @startuml/@enduml, box-drawing characters
 
 8. **For Tables:**
-   - Copy complete tables with ALL rows into \`narrative.structure\` or \`narrative.features\`
+   - Copy complete tables with ALL rows into \`narrative.structure\` or \`narrative.highlights\`
    - Preserve column headers and every data row - do not summarize
 
 ### What "Preserve" Means:
@@ -526,7 +541,7 @@ content: {
 **Secondary fields for structured details:**
 - \`narrative.rules\` - Exact rule/constraint text from docs
 - \`narrative.examples\` - Complete example code with full context
-- \`narrative.features\` - Full feature descriptions with all details
+- \`narrative.highlights\` - Key highlights, capabilities, deliverables, or notable outcomes
 - \`narrative.structure\` - Complete structural documentation
 - \`narrative.dependencies\` - Full dependency information
 - \`rawConcept.patterns\` - All patterns with complete regex/validation strings
@@ -558,7 +573,7 @@ Extract ALL of the following - COMPLETE and VERBATIM:
 8. **Examples** - Copy full example code with all context
 9. **Metadata** - Capture authors, versions, dates from files
 10. **Diagrams** - Mermaid diagrams, PlantUML, ASCII art flow charts, sequence diagrams (use \`narrative.diagrams\` with type and content - preserve verbatim)
-11. **Tables** - Data tables with ALL rows preserved (use \`narrative.structure\` or \`narrative.features\`)
+11. **Tables** - Data tables with ALL rows preserved (use \`narrative.structure\` or \`narrative.highlights\`)
 12. **Procedures** - Step-by-step instructions, numbered workflows (use \`narrative.rules\`)
 
 ## Curation Process
@@ -740,41 +755,67 @@ await tools.curate([{
      * This avoids token limits entirely - data is stored in REPL, not in prompt.
      */
     // eslint-disable-next-line max-params
-    async executeIterative(agent, packResult, userContext, folderPath, taskId) {
+    async executeIterative(agent, packResult, userContext, folderPath, taskId, projectRoot) {
         // Step 1: Generate repomix-style XML (single string with all file contents)
         const packedXml = this.folderPackService.generateXml(packResult);
         const xmlSizeInMB = (packedXml.length / (1024 * 1024)).toFixed(2);
-        console.log(`[FolderPackExecutor] Generated XML: ${xmlSizeInMB} MB for ${packResult.fileCount} files`);
+        folderPackLog(`Generated XML: ${xmlSizeInMB} MB for ${packResult.fileCount} files`);
         // Step 2: Write XML to temporary file (avoids token limits, works with any agent)
         // This approach: file path (~50 bytes) sent to LLM, data stays on disk
-        // IMPORTANT: Write to CWD (not /tmp) so sandbox can access it
-        const tmpFilePath = path.join(process.cwd(), `.byterover-curate-${taskId}.xml`);
-        console.log(`[FolderPackExecutor] Writing folder data to temp file: ${tmpFilePath}`);
+        // IMPORTANT: Write to project root (not /tmp) so sandbox can access it
+        const tmpFilePath = path.join(projectRoot, `.byterover-curate-${taskId}.xml`);
+        folderPackLog(`Writing folder data to temp file: ${tmpFilePath}`);
         try {
             await fs.writeFile(tmpFilePath, packedXml, 'utf8');
-            console.log(`[FolderPackExecutor] Successfully wrote ${xmlSizeInMB} MB to temp file`);
+            folderPackLog(`Successfully wrote ${xmlSizeInMB} MB to temp file`);
         }
         catch (error) {
             throw new Error(`Failed to write temp file: ${error instanceof Error ? error.message : String(error)}`);
         }
-        // Step 3: Execute main curation task with file path reference
-        const prompt = this.buildIterativePromptWithFileAccess(userContext, folderPath, tmpFilePath, packResult.fileCount, packResult.totalLines);
+        // Create per-task session for parallel isolation (own sandbox + history + LLM service)
+        const taskSessionId = await agent.createTaskSession(taskId, 'curate', { mapRootEligible: true });
+        // Step 3: Store full instructions as sandbox variable (lazy prompt loading).
+        // This saves ~12-15K tokens by keeping the massive instruction set out of the prompt.
+        // The LLM reads instructions on-demand via code_exec.
+        const fullInstructions = this.buildIterativePromptWithFileAccess(userContext, folderPath, tmpFilePath, packResult.fileCount, packResult.totalLines);
+        // Replace hyphens with underscores: UUIDs have hyphens which are invalid in JS identifiers.
+        // The LLM uses underscores when writing code-exec calls — matching curate-executor pattern.
+        const taskIdSafe = taskId.replaceAll('-', '_');
+        const instructionsVar = `__curate_instructions_${taskIdSafe}`;
+        agent.setSandboxVariableOnSession(taskSessionId, instructionsVar, fullInstructions);
+        // Compact prompt with variable reference and essential metadata
+        const contextSection = userContext?.trim() ? `\nUser context: ${userContext}\n` : '';
+        const compactPrompt = [
+            `# Folder Curation Task`,
+            ``,
+            `Folder: ${folderPath} (${packResult.fileCount} files, ${packResult.totalLines} lines)`,
+            `Data file: \`${tmpFilePath}\` (repomix-style XML format)`,
+            `Full instructions: variable \`${instructionsVar}\``,
+            contextSection,
+            `**Start by reading instructions**: Use code_exec to read \`${instructionsVar}.slice(0, 5000)\` for the strategy section, then \`${instructionsVar}.slice(5000, 10000)\` for content rules.`,
+            `Use \`tools.readFile()\` and \`tools.grep()\` inside code_exec to process the XML data file.`,
+            `Use \`tools.curate()\` to create knowledge topics. Use \`setFinalResult()\` when done.`,
+        ]
+            .filter(Boolean)
+            .join('\n');
         let response;
         try {
-            response = await agent.execute(prompt, {
+            response = await agent.executeOnSession(taskSessionId, compactPrompt, {
                 executionContext: { commandType: 'curate' },
                 taskId,
             });
         }
         finally {
-            // Step 4: Clean up - delete temp file
-            console.log(`[FolderPackExecutor] Cleaning up temp file`);
+            // Clean up task session (sandbox + history)
+            await agent.deleteTaskSession(taskSessionId);
+            // Clean up temp file
+            folderPackLog(`Cleaning up temp file: ${tmpFilePath}`);
             try {
                 await fs.unlink(tmpFilePath);
-                console.log(`[FolderPackExecutor] Temp file cleanup successful`);
+                folderPackLog(`Temp file cleanup successful`);
             }
             catch (error) {
-                console.warn(`[FolderPackExecutor] Temp file cleanup warning (non-fatal):`, error);
+                folderPackLog(`Temp file cleanup warning (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         return response;

package/dist/server/infra/executor/pre-compaction/compaction-escalation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export from shared utilities.
+ * Original implementation moved to src/shared/utils/escalation-utils.ts
+ * to allow cross-layer reuse (both server/ and agent/ can import).
+ */
+export { buildDeterministicFallbackCompaction, type CompactionEscalationTier, estimateTokens, isCompactionOutputValid, shouldAcceptCompactionOutput, withAggressiveCompactionDirective, } from '../../../../shared/utils/escalation-utils.js';

package/dist/server/infra/executor/pre-compaction/compaction-escalation.js

@@ -0,0 +1,6 @@
+/**
+ * Re-export from shared utilities.
+ * Original implementation moved to src/shared/utils/escalation-utils.ts
+ * to allow cross-layer reuse (both server/ and agent/ can import).
+ */
+export { buildDeterministicFallbackCompaction, estimateTokens, isCompactionOutputValid, shouldAcceptCompactionOutput, withAggressiveCompactionDirective, } from '../../../../shared/utils/escalation-utils.js';

package/dist/server/infra/executor/pre-compaction/index.d.ts

@@ -0,0 +1,3 @@
+export type { CompactionEscalationTier } from './compaction-escalation.js';
+export { PRE_COMPACTION_CHAR_THRESHOLD, PreCompactionService } from './pre-compaction-service.js';
+export type { PreCompactionResult } from './pre-compaction-service.js';

package/dist/server/infra/executor/pre-compaction/index.js

@@ -0,0 +1 @@
+export { PRE_COMPACTION_CHAR_THRESHOLD, PreCompactionService } from './pre-compaction-service.js';

package/dist/server/infra/executor/pre-compaction/pre-compaction-service.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pre-Compaction Service — Three-Level Escalation for curation context.
+ *
+ * Compacts large source context BEFORE the curation agent sees it,
+ * saving the agent from wasting iterations on chunking/extraction code.
+ *
+ * Fail-open: any error returns the original context unchanged.
+ */
+import type { ICipherAgent } from '../../../../agent/core/interfaces/i-cipher-agent.js';
+import { type CompactionEscalationTier } from './compaction-escalation.js';
+/**
+ * Character threshold below which compaction is skipped.
+ * Re-exported from shared constant for backwards compatibility.
+ */
+export declare const PRE_COMPACTION_CHAR_THRESHOLD = 20000;
+/**
+ * Result of a pre-compaction operation.
+ */
+export interface PreCompactionResult {
+    /** The (possibly compacted) context text */
+    context: string;
+    /** Original character count before compaction */
+    originalCharCount: number;
+    /** Whether compaction was actually applied */
+    preCompacted: boolean;
+    /** Which escalation tier succeeded (only set if preCompacted is true) */
+    preCompactionTier?: CompactionEscalationTier;
+}
+/**
+ * Service that pre-compacts curation context using three-level escalation.
+ *
+ * Level 1 (Normal): LLM compaction with standard prompt
+ * Level 2 (Aggressive): LLM compaction with aggressive prompt
+ * Level 3 (Fallback): Deterministic truncation (no LLM, always converges)
+ */
+export declare class PreCompactionService {
+    /**
+     * Compact context if it exceeds the character threshold.
+     *
+     * Fail-open: any error during compaction returns the original context.
+     * Deterministic fallback is only used when the LLM responded but with
+     * unacceptable output — never when the LLM itself errored.
+     * Manages its own session lifecycle (creates + deletes a task session).
+     *
+     * @param agent - The CipherAgent to use for LLM calls
+     * @param context - The source context to compact
+     * @param taskId - Parent task ID (compaction uses `${taskId}__compact`)
+     * @returns PreCompactionResult with the (possibly compacted) context
+     */
+    compact(agent: ICipherAgent, context: string, taskId: string): Promise<PreCompactionResult>;
+    /**
+     * Execute a single compaction pass via the agent.
+     *
+     * Returns a discriminated result so the caller can distinguish
+     * "LLM responded with bad output" from "LLM errored" — the former
+     * should escalate to the next tier, the latter should fail-open.
+     */
+    private executeCompactionPass;
+}

package/dist/server/infra/executor/pre-compaction/pre-compaction-service.js

@@ -0,0 +1,124 @@
+/**
+ * Pre-Compaction Service — Three-Level Escalation for curation context.
+ *
+ * Compacts large source context BEFORE the curation agent sees it,
+ * saving the agent from wasting iterations on chunking/extraction code.
+ *
+ * Fail-open: any error returns the original context unchanged.
+ */
+import { CURATION_CHAR_THRESHOLD } from '../../../../shared/constants/curation.js';
+import { buildDeterministicFallbackCompaction, estimateTokens, isCompactionOutputValid, shouldAcceptCompactionOutput, } from './compaction-escalation.js';
+import { buildCompactionSystemPrompt, buildCompactionUserMessage } from './prompts.js';
+/**
+ * Character threshold below which compaction is skipped.
+ * Re-exported from shared constant for backwards compatibility.
+ */
+export const PRE_COMPACTION_CHAR_THRESHOLD = CURATION_CHAR_THRESHOLD;
+/**
+ * Service that pre-compacts curation context using three-level escalation.
+ *
+ * Level 1 (Normal): LLM compaction with standard prompt
+ * Level 2 (Aggressive): LLM compaction with aggressive prompt
+ * Level 3 (Fallback): Deterministic truncation (no LLM, always converges)
+ */
+export class PreCompactionService {
+    /**
+     * Compact context if it exceeds the character threshold.
+     *
+     * Fail-open: any error during compaction returns the original context.
+     * Deterministic fallback is only used when the LLM responded but with
+     * unacceptable output — never when the LLM itself errored.
+     * Manages its own session lifecycle (creates + deletes a task session).
+     *
+     * @param agent - The CipherAgent to use for LLM calls
+     * @param context - The source context to compact
+     * @param taskId - Parent task ID (compaction uses `${taskId}__compact`)
+     * @returns PreCompactionResult with the (possibly compacted) context
+     */
+    async compact(agent, context, taskId) {
+        const originalCharCount = context.length;
+        const failOpen = { context, originalCharCount, preCompacted: false };
+        if (originalCharCount <= PRE_COMPACTION_CHAR_THRESHOLD) {
+            return failOpen;
+        }
+        const inputTokens = estimateTokens(context);
+        const compactionTaskId = `${taskId}__compact`;
+        try {
+            const sessionId = await agent.createTaskSession(compactionTaskId, 'query');
+            try {
+                // --- Pass 1: Normal compaction ---
+                const normalPass = await this.executeCompactionPass({ agent, aggressive: false, context, sessionId, taskId: compactionTaskId });
+                if (normalPass.errored)
+                    return failOpen;
+                if (normalPass.output && shouldAcceptCompactionOutput(normalPass.output, inputTokens) && isCompactionOutputValid(normalPass.output)) {
+                    return {
+                        context: normalPass.output.trim(),
+                        originalCharCount,
+                        preCompacted: true,
+                        preCompactionTier: 'normal',
+                    };
+                }
+                // --- Pass 2: Aggressive compaction ---
+                const aggressivePass = await this.executeCompactionPass({ agent, aggressive: true, context, sessionId, taskId: compactionTaskId });
+                if (aggressivePass.errored)
+                    return failOpen;
+                if (aggressivePass.output && shouldAcceptCompactionOutput(aggressivePass.output, inputTokens) && isCompactionOutputValid(aggressivePass.output)) {
+                    return {
+                        context: aggressivePass.output.trim(),
+                        originalCharCount,
+                        preCompacted: true,
+                        preCompactionTier: 'aggressive',
+                    };
+                }
+                // --- Pass 3: Deterministic fallback ---
+                // Only reached when both passes got LLM responses but output was unacceptable
+                const fallbackResult = buildDeterministicFallbackCompaction({
+                    inputTokens,
+                    sourceText: context,
+                    suffixLabel: 'pre-curation compaction',
+                });
+                return {
+                    context: fallbackResult,
+                    originalCharCount,
+                    preCompacted: true,
+                    preCompactionTier: 'fallback',
+                };
+            }
+            finally {
+                await agent.deleteTaskSession(sessionId);
+            }
+        }
+        catch {
+            // Fail-open: return original context on ANY error
+            return failOpen;
+        }
+    }
+    /**
+     * Execute a single compaction pass via the agent.
+     *
+     * Returns a discriminated result so the caller can distinguish
+     * "LLM responded with bad output" from "LLM errored" — the former
+     * should escalate to the next tier, the latter should fail-open.
+     */
+    async executeCompactionPass(options) {
+        try {
+            const systemPrompt = buildCompactionSystemPrompt();
+            const userMessage = buildCompactionUserMessage(options.context, options.aggressive);
+            const prompt = `${systemPrompt}\n\n${userMessage}`;
+            const response = await options.agent.executeOnSession(options.sessionId, prompt, {
+                executionContext: {
+                    clearHistory: true,
+                    commandType: 'query',
+                    maxIterations: 1,
+                    maxTokens: 4096,
+                    temperature: 0.3,
+                },
+                taskId: options.taskId,
+            });
+            return { errored: false, output: response || undefined };
+        }
+        catch {
+            return { errored: true, output: undefined };
+        }
+    }
+}

package/dist/server/infra/executor/pre-compaction/prompts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Compaction prompts for pre-curation context compaction.
+ *
+ * Self-contained prompts that steer the LLM away from query-mode policy
+ * (which would try to search the KB). The real guardrail against
+ * non-compaction responses is isCompactionOutputValid().
+ */
+/**
+ * Build the system prompt for compaction.
+ *
+ * Opens with a clear, self-contained instruction that overrides
+ * query-mode's "answers from KB only" rules. Note: prompt-level override
+ * is best-effort; isCompactionOutputValid() is the actual guardrail.
+ */
+export declare function buildCompactionSystemPrompt(): string;
+/**
+ * Build the user message for a compaction pass.
+ *
+ * Wraps the context in <source_content> tags for clear delimitation.
+ *
+ * @param context - The source text to compact
+ * @param aggressive - Whether this is the aggressive (pass 2) attempt
+ */
+export declare function buildCompactionUserMessage(context: string, aggressive: boolean): string;