@caupulican/pi-agent-core 0.81.2 → 0.81.4

package/dist/compaction/compaction.js

@@ -7,7 +7,9 @@
 import { completeSimple } from "@caupulican/pi-ai";
 import { convertToLlm, createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "../messages.js";
 import { buildSessionContext } from "../session/session-manager.js";
+import { extractCompactionFacts, renderFactsBlock } from "./extraction.js";
 import { computeFileLists, createFileOps, extractFileOpsFromMessage, formatFileOperations, SUMMARIZATION_SYSTEM_PROMPT, serializeConversation, } from "./utils.js";
+import { buildRetryPrompt, verifySummary } from "./verification.js";
 /**
  * Extract file operations from messages and previous compaction entries.
  */
@@ -379,76 +381,35 @@ export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens) {
 // ============================================================================
 // Summarization
 // ============================================================================
-const SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
-
-Use this EXACT format:
-
-## Goal
-[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
-
+const SUMMARIZATION_PROMPT = `Checkpoint the conversation above. Format from your instructions, sections in this order:
+## Active Task
+### Mandatory Rules
+## Files
+## Done
 ## Constraints & Preferences
-- [Any constraints, preferences, or requirements mentioned by user]
-- [Or "(none)" if none were mentioned]
-
-## Progress
-### Done
-- [x] [Completed tasks/changes]
-
-### In Progress
-- [ ] [Current work]
-
-### Blocked
-- [Issues preventing progress, if any]
-
 ## Key Decisions
-- **[Decision]**: [Brief rationale]
-
-## Next Steps
-1. [Ordered list of what should happen next]
-
+## Blocked / Open
 ## Critical Context
-- [Any data, examples, or references needed to continue]
-- [Or "(none)" if not applicable]
-
-Keep each section concise. Preserve exact file paths, function names, and error messages.`;
-const UPDATE_SUMMARIZATION_PROMPT = `The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.
-
-Update the existing structured summary with new information. RULES:
-- PRESERVE all existing information from the previous summary
-- ADD new progress, decisions, and context from the new messages
-- UPDATE the Progress section: move items from "In Progress" to "Done" when completed
-- UPDATE "Next Steps" based on what was accomplished
-- PRESERVE exact file paths, function names, and error messages
-- If something is no longer relevant, you may remove it
 
-Use this EXACT format:
+Pre-extracted facts (verified by tooling — include ALL of them, merged with what you read):
+<facts>
+{FACTS_BLOCK}
+</facts>
 
-## Goal
-[Preserve existing goals, add new ones if the task expanded]
+Budget: ~{BUDGET} tokens. Concrete beats complete.`;
+const UPDATE_SUMMARIZATION_PROMPT = `Update the checkpoint in <previous-summary> with the NEW turns above. RULES:
+- PRESERVE every existing ### Mandatory Rules bullet VERBATIM; append new ones.
+- Continue the ## Done numbering; move finished work from Blocked/Open.
+- Update ## Active Task to the newest unfulfilled user input; apply the cancellation rule.
+- Keep ## Files current (add new, keep still-relevant, drop obsolete).
+- Preserve exact paths, commands, errors.
 
-## Constraints & Preferences
-- [Preserve existing, add new ones discovered]
-
-## Progress
-### Done
-- [x] [Include previously done items AND newly completed items]
-
-### In Progress
-- [ ] [Current work - update based on progress]
-
-### Blocked
-- [Current blockers - remove if resolved]
-
-## Key Decisions
-- **[Decision]**: [Brief rationale] (preserve all previous, add new)
+Same section order. Pre-extracted facts:
+<facts>
+{FACTS_BLOCK}
+</facts>
 
-## Next Steps
-1. [Update based on current state]
-
-## Critical Context
-- [Preserve important context, add new if needed]
-
-Keep each section concise. Preserve exact file paths, function names, and error messages.`;
+Budget: ~{BUDGET} tokens.`;
 function createSummarizationOptions(model, maxTokens, apiKey, headers, signal, thinkingLevel) {
     const options = { maxTokens, signal, apiKey, headers };
     if (model.reasoning && thinkingLevel && thinkingLevel !== "off") {
@@ -467,50 +428,177 @@ async function completeSummarization(model, context, options, streamFn) {
  * Generate a summary of the conversation using the LLM.
  * If previousSummary is provided, uses the update prompt to merge.
  */
-export async function generateSummary(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, preDigest) {
-    const maxTokens = Math.min(Math.floor(0.8 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
-    // Use update prompt if we have a previous summary, otherwise initial prompt
-    let basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;
+export async function generateSummary(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, preDigest, factsBlock = "files:\nactions:\nprohibitions:", chunked = false) {
+    const summaryBudget = getSummaryBudget(reserveTokens, model, factsBlock);
+    const maxTokens = summaryBudget;
+    let promptSuffix = fillPromptTemplate(previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT, factsBlock, summaryBudget);
     if (customInstructions) {
-        basePrompt = `${basePrompt}\n\nAdditional focus: ${customInstructions}`;
+        promptSuffix = `${promptSuffix}\n\nAdditional focus: ${customInstructions}`;
     }
-    // Serialize conversation to text so model doesn't try to continue it
-    // Convert to LLM messages first (handles custom types like bashExecution, custom, etc.)
     const llmMessages = convertToLlm(currentMessages);
     let conversationText = serializeConversation(llmMessages);
-    // Brain-curation surface 3 (opt-in, injected by the session): pre-digest old chunks locally
-    // before the frontier summarization call. Best-effort — failure keeps the verbatim text.
     if (preDigest) {
         try {
             conversationText = await preDigest(conversationText, signal);
         }
         catch {
-            // verbatim fallback
+            // Keep the verbatim conversation when an optional pre-digest fails.
         }
     }
-    // Build the prompt with conversation wrapped in tags
+    const inputBound = getSummarizerInputBound(model, maxTokens);
+    const initialPromptText = buildSummarizationPrompt(conversationText, previousSummary, promptSuffix);
+    if (estimateStringTokens(initialPromptText) > inputBound) {
+        if (!chunked) {
+            throw new Error("input-overflow: summarization request exceeds summarizer window");
+        }
+        conversationText = await summarizeChunks(conversationText, model, maxTokens, apiKey, headers, signal, thinkingLevel, streamFn, inputBound);
+    }
+    const promptText = buildSummarizationPrompt(conversationText, previousSummary, promptSuffix);
+    const response = await completeSummarization(model, {
+        systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+        messages: [
+            {
+                role: "user",
+                content: [{ type: "text", text: promptText }],
+                timestamp: Date.now(),
+            },
+        ],
+    }, createSummarizationOptions(model, maxTokens, apiKey, headers, signal, thinkingLevel), streamFn);
+    if (response.stopReason === "error") {
+        throw new Error(`Summarization failed: ${response.errorMessage || "Unknown error"}`);
+    }
+    // A length-stopped checkpoint silently lost its tail sections — gating it as if complete
+    // guarantees a verification failure. Fail loudly so the compaction ladder escalates instead.
+    if (response.stopReason === "length") {
+        throw new Error("summary-length-stop: summarizer hit its output cap before completing the checkpoint");
+    }
+    return truncateSummaryToBudget(extractTextContent(response), summaryBudget);
+}
+function fillPromptTemplate(template, factsBlock, budget) {
+    return template.replaceAll("{FACTS_BLOCK}", factsBlock).replaceAll("{BUDGET}", String(budget));
+}
+const SUMMARY_BUDGET_BASE_TOKENS = 1_500;
+/** Hard ceiling for the facts-scaled summary budget; also the worst case selection must assume. */
+export const SUMMARY_BUDGET_MAX_TOKENS = 4_000;
+/** Prompt-side margin beyond the raw conversation input (system prompt, tags, instructions). */
+const SUMMARIZER_PROMPT_MARGIN_TOKENS = 2_000;
+function getSummaryBudget(reserveTokens, model, factsBlock) {
+    const modelMaxTokens = model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY;
+    // The verification gate demands the summary restate every extracted fact (modified files,
+    // actions, rules). A fixed budget makes large spans structurally fail: the model length-stops
+    // and the gated sections are the casualties. Scale the budget with the demand, bounded.
+    const factsTokens = factsBlock ? estimateStringTokens(factsBlock) : 0;
+    const demandBudget = Math.min(SUMMARY_BUDGET_MAX_TOKENS, Math.max(SUMMARY_BUDGET_BASE_TOKENS, factsTokens + 500));
+    return Math.max(1, Math.min(demandBudget, Math.floor(0.8 * reserveTokens), modelMaxTokens));
+}
+function getSummarizerInputBound(model, maxTokens) {
+    const contextWindow = model.contextWindow > 0 ? model.contextWindow : Number.POSITIVE_INFINITY;
+    return contextWindow === Number.POSITIVE_INFINITY
+        ? contextWindow
+        : Math.max(1, contextWindow - maxTokens - SUMMARIZER_PROMPT_MARGIN_TOKENS);
+}
+/**
+ * Whether a candidate summarizer can ingest a summarization input of the given size in ONE
+ * request (unchunked), using the same window arithmetic as {@link getSummarizerInputBound} with
+ * the worst-case (facts-scaled) summary budget. Hosts use this at SELECTION time: a model that
+ * fails this must not be handed the job — chunking cannot rescue recall-gated summarization, and
+ * local servers silently truncate over-window prompts instead of erroring.
+ */
+export function summarizerCanIngest(model, estimatedInputTokens) {
+    const contextWindow = model.contextWindow > 0 ? model.contextWindow : Number.POSITIVE_INFINITY;
+    if (contextWindow === Number.POSITIVE_INFINITY)
+        return true;
+    return estimatedInputTokens <= contextWindow - SUMMARY_BUDGET_MAX_TOKENS - SUMMARIZER_PROMPT_MARGIN_TOKENS;
+}
+function buildSummarizationPrompt(conversationText, previousSummary, promptSuffix) {
     let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
     if (previousSummary) {
         promptText += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;
     }
-    promptText += basePrompt;
-    const summarizationMessages = [
-        {
-            role: "user",
-            content: [{ type: "text", text: promptText }],
-            timestamp: Date.now(),
-        },
-    ];
-    const completionOptions = createSummarizationOptions(model, maxTokens, apiKey, headers, signal, thinkingLevel);
-    const response = await completeSummarization(model, { systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages }, completionOptions, streamFn);
-    if (response.stopReason === "error") {
-        throw new Error(`Summarization failed: ${response.errorMessage || "Unknown error"}`);
+    return promptText + promptSuffix;
+}
+async function summarizeChunks(conversationText, model, maxTokens, apiKey, headers, signal, thinkingLevel, streamFn, inputBound) {
+    const maxChunkTokens = Math.max(1, inputBound);
+    const maxChunkChars = Math.max(1, maxChunkTokens * 4);
+    const chunks = splitText(conversationText, maxChunkChars);
+    const retainedChunks = chunks.slice(-4);
+    const omittedChunks = chunks.length - retainedChunks.length;
+    const summaries = [];
+    for (let i = 0; i < retainedChunks.length; i++) {
+        const promptText = `<conversation-chunk index="${i + 1}" total="${retainedChunks.length}">\n${retainedChunks[i]}\n</conversation-chunk>\n\nSummarize this chunk for a later checkpoint merge. Preserve exact file paths, commands, errors, user prohibitions, and active work. Output concise notes only.`;
+        const response = await completeSummarization(model, {
+            systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+            messages: [
+                {
+                    role: "user",
+                    content: [{ type: "text", text: promptText }],
+                    timestamp: Date.now(),
+                },
+            ],
+        }, createSummarizationOptions(model, maxTokens, apiKey, headers, signal, thinkingLevel), streamFn);
+        if (response.stopReason === "error") {
+            throw new Error(`Summarization failed: ${response.errorMessage || "Unknown error"}`);
+        }
+        summaries.push(extractTextContent(response));
     }
-    const textContent = response.content
-        .filter((c) => c.type === "text")
-        .map((c) => c.text)
+    const omittedNote = omittedChunks > 0
+        ? `## Critical Context\n${omittedChunks} older oversized chunks omitted; deterministic facts supplied separately.\n\n`
+        : "";
+    return `${omittedNote}${summaries.join("\n\n")}`;
+}
+function splitText(text, maxChars) {
+    const chunks = [];
+    for (let start = 0; start < text.length; start += maxChars) {
+        chunks.push(text.slice(start, start + maxChars));
+    }
+    return chunks.length > 0 ? chunks : [""];
+}
+function extractTextContent(message) {
+    return message.content
+        .filter((content) => content.type === "text")
+        .map((content) => content.text)
         .join("\n");
-    return textContent;
+}
+function truncateSummaryToBudget(summary, budget) {
+    const maxTokens = Math.floor(budget * 1.3);
+    if (estimateStringTokens(summary) <= maxTokens) {
+        return summary;
+    }
+    let current = summary;
+    // Never drop "Files" or "Done" here: the verification gate checks exactly those sections
+    // (files-modified/read-recall, actions-overlap), so deleting them guarantees gate failure.
+    for (const heading of ["Critical Context", "Blocked / Open", "Key Decisions", "Constraints & Preferences"]) {
+        const next = removeSummarySection(current, heading);
+        if (next === current) {
+            continue;
+        }
+        current = next;
+        if (estimateStringTokens(current) <= maxTokens) {
+            return current;
+        }
+    }
+    return current;
+}
+function removeSummarySection(summary, heading) {
+    const lines = summary.split(/\r?\n/);
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        const match = /^(?:##|###)\s+(.+?)\s*$/.exec(line);
+        if (match) {
+            skipping = match[1].trim().toLowerCase() === heading.toLowerCase();
+            if (skipping) {
+                continue;
+            }
+        }
+        if (!skipping) {
+            kept.push(line);
+        }
+    }
+    return kept.join("\n").trim();
+}
+function estimateStringTokens(text) {
+    return Math.ceil(text.length / 4);
 }
 export function prepareCompaction(pathEntries, settings) {
     if (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === "compaction") {
@@ -565,6 +653,7 @@ export function prepareCompaction(pathEntries, settings) {
             extractFileOpsFromMessage(msg, fileOps);
         }
     }
+    const facts = extractCompactionFacts(pathEntries, boundaryStart, historyEnd);
     return {
         firstKeptEntryId,
         messagesToSummarize,
@@ -573,6 +662,7 @@ export function prepareCompaction(pathEntries, settings) {
         tokensBefore,
         previousSummary,
         fileOps,
+        facts,
         settings,
     };
 }
@@ -600,24 +690,54 @@ Be concise. Focus on what's needed to understand the kept suffix.`;
  * @param preparation - Pre-calculated preparation from prepareCompaction()
  * @param customInstructions - Optional custom focus for the summary
  */
-export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, streamFn, preDigest) {
-    const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, settings, } = preparation;
-    // Generate summaries (can be parallel if both needed) and merge into one
-    let summary;
-    if (isSplitTurn && turnPrefixMessages.length > 0) {
-        // Generate both summaries in parallel
-        const [historyResult, turnPrefixResult] = await Promise.all([
-            messagesToSummarize.length > 0
-                ? generateSummary(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, preDigest)
-                : Promise.resolve("No prior history."),
-            generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, headers, signal, thinkingLevel, streamFn),
-        ]);
-        // Merge into single summary
-        summary = `${historyResult}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixResult}`;
+export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, streamFn, preDigest, executionOptions) {
+    const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, settings, facts: factsFromPreparation, } = preparation;
+    const facts = factsFromPreparation ?? {
+        files: [],
+        actions: [],
+        prohibitions: [],
+        cancelledText: "",
+        activeTaskSource: "",
+    };
+    const factsBlock = renderFactsBlock(facts);
+    let verification;
+    let summary = "";
+    if (isSplitTurn && messagesToSummarize.length > 0) {
+        let historySummary = "No prior history.";
+        let historyInstructions = customInstructions;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            historySummary = await generateSummary(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, historyInstructions, previousSummary, thinkingLevel, streamFn, preDigest, factsBlock, executionOptions?.chunked ?? false);
+            verification = verifySummary(historySummary, facts);
+            if (verification.ok) {
+                break;
+            }
+            if (attempt >= 1) {
+                if (executionOptions?.allowVerificationFailure) {
+                    break;
+                }
+                throw new Error(`gate-failed: ${formatVerificationFailures(verification)}`);
+            }
+            historyInstructions = buildRetryPrompt(verification, historySummary);
+        }
+        const turnPrefixSummary = await generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, headers, signal, thinkingLevel, streamFn);
+        summary = `${historySummary}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixSummary}`;
     }
     else {
-        // Just generate history summary
-        summary = await generateSummary(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, preDigest);
+        let customSummaryInstructions = customInstructions;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            summary = await generateSummary(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, customSummaryInstructions, previousSummary, thinkingLevel, streamFn, preDigest, factsBlock, executionOptions?.chunked ?? false);
+            verification = verifySummary(summary, facts);
+            if (verification.ok) {
+                break;
+            }
+            if (attempt >= 1) {
+                if (executionOptions?.allowVerificationFailure) {
+                    break;
+                }
+                throw new Error(`gate-failed: ${formatVerificationFailures(verification)}`);
+            }
+            customSummaryInstructions = buildRetryPrompt(verification, summary);
+        }
     }
     // Compute file lists and append to summary
     const { readFiles, modifiedFiles } = computeFileLists(fileOps);
@@ -625,6 +745,63 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
     if (!firstKeptEntryId) {
         throw new Error("First kept entry has no UUID - session may need migration");
     }
+    return {
+        summary,
+        firstKeptEntryId,
+        tokensBefore,
+        details: { readFiles, modifiedFiles },
+        verification,
+    };
+}
+function formatVerificationFailures(verification) {
+    return verification.failures.map((failure) => `${failure.check}: ${failure.detail}`).join(", ");
+}
+export function createDeterministicCompaction(preparation) {
+    const { firstKeptEntryId, tokensBefore, fileOps, facts } = preparation;
+    if (!firstKeptEntryId) {
+        throw new Error("First kept entry has no UUID - session may need migration");
+    }
+    const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+    const factsText = renderFactsBlock(facts ?? {
+        files: [],
+        actions: [],
+        prohibitions: [],
+        cancelledText: "",
+        activeTaskSource: "",
+    });
+    const fileLines = facts?.files.length
+        ? facts.files.map((file) => `- ${file.path} — ${file.note || file.kind} (${file.kind})`)
+        : [`- read: ${readFiles.length}`, `- modified: ${modifiedFiles.length}`];
+    const mandatoryRuleLines = facts?.prohibitions.length ? facts.prohibitions.map((rule) => `- ${rule}`) : ["(none)"];
+    const doneLines = facts?.actions.length
+        ? facts.actions.map((action, index) => `${index + 1}. ${action}`)
+        : ["1. CHECKPOINT deterministic fallback — repeated compaction retries exhausted"];
+    const summary = [
+        "## Active Task",
+        facts?.activeTaskSource ? `User: ${facts.activeTaskSource}` : "Continue from the deterministic compact snapshot.",
+        "",
+        "### Mandatory Rules",
+        ...mandatoryRuleLines,
+        "",
+        "## Files",
+        ...fileLines,
+        "",
+        "## Done",
+        ...doneLines,
+        "",
+        "## Constraints & Preferences",
+        "Preserve exact file paths, commands, line numbers, and error strings.",
+        "",
+        "## Key Decisions",
+        "- Deterministic checkpoint used after repeated compaction retries.",
+        "",
+        "## Blocked / Open",
+        "(none)",
+        "",
+        "## Critical Context",
+        "- Deterministic facts-only checkpoint; no LLM summary was accepted.",
+        factsText,
+    ].join("\n");
     return {
         summary,
         firstKeptEntryId,