@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/context/compact-llm.d.ts

@@ -0,0 +1,25 @@
+/**
+ * LLM-backed structured conversation compaction.
+ *
+ * Generates a 9-section summary of the older turns via the provider's
+ * completion API, replacing the dropped history with a single system
+ * message. Falls back to the heuristic `compactMessages` if the LLM call
+ * fails.
+ */
+import type { CompactOptions, CompactResult } from "./compact.js";
+import type { Message, Provider, ProviderMessage, ThinkingLevel } from "../types.js";
+export interface LLMCompactOptions extends CompactOptions {
+    provider: Provider;
+    model: string;
+    thinkingLevel?: ThinkingLevel;
+}
+export declare const COMPACT_SYSTEM_PROMPT = "You are a conversation summarizer. Your job is to produce a structured\nsummary of an earlier portion of a software-engineering assistant's\nconversation so that the assistant can continue working without the full\nhistory. Preserve fidelity over brevity where the user's intent, file\npaths, or decisions are concerned. Output ONLY the summary, no preamble.";
+export declare const COMPACT_INSTRUCTIONS = "Summarize the conversation above using exactly these 9 sections, each\npreceded by the literal heading on its own line. If a section has no\ncontent, write \"None\".\n\n1. Primary Request and Intent\n   - What the user ultimately wants, in their own framing.\n\n2. Key Technical Concepts\n   - Libraries, frameworks, architectural patterns referenced.\n\n3. Files and Code Sections\n   - Files read, written, or discussed. Include full paths and a one-line note.\n\n4. Errors and Fixes\n   - Bugs encountered and how they were resolved.\n\n5. Problem Solving\n   - Non-trivial debugging or design decisions.\n\n6. All User Messages\n   - Every user message, verbatim, in order. Do not summarize here.\n\n7. Pending Tasks\n   - Work that was planned but not yet completed.\n\n8. Current Work\n   - What was being actively worked on when the summary was taken.\n\n9. Optional Next Step\n   - The single most natural next action, if obvious.";
+export declare function compactMessagesWithLLM(messages: Message[], options: LLMCompactOptions): Promise<CompactResult>;
+/**
+ * Build the two-message prompt that asks the model for a 9-section summary of
+ * `oldMessages`. Shared by the non-streaming overflow path (`generateSummary`)
+ * and the streaming manual `/compact` path (`Agent.summarizeForCompaction`).
+ */
+export declare function buildCompactionPromptMessages(oldMessages: Message[], userContext?: string): ProviderMessage[];
+export declare function serializeTranscript(messages: Message[]): string;

package/dist/context/compact-llm.js

@@ -0,0 +1,175 @@
+/**
+ * LLM-backed structured conversation compaction.
+ *
+ * Generates a 9-section summary of the older turns via the provider's
+ * completion API, replacing the dropped history with a single system
+ * message. Falls back to the heuristic `compactMessages` if the LLM call
+ * fails.
+ */
+import { buildCompactionSummaryMessage, clonePinnedUserMessage, collectCompactionFileOps, compactMessages as compactMessagesHeuristic, findFirstRealUserIndex, isCompactionSummaryMessage, isRealUserMessage, messageText, splitLeadingContext, } from "./compact.js";
+import { sanitizeInternalReminderBlocks } from "../agent/internal-reminder-sanitizer.js";
+import { appendFileBlocks, stripFileBlocks } from "./compaction-files.js";
+export const COMPACT_SYSTEM_PROMPT = `You are a conversation summarizer. Your job is to produce a structured
+summary of an earlier portion of a software-engineering assistant's
+conversation so that the assistant can continue working without the full
+history. Preserve fidelity over brevity where the user's intent, file
+paths, or decisions are concerned. Output ONLY the summary, no preamble.`;
+export const COMPACT_INSTRUCTIONS = `Summarize the conversation above using exactly these 9 sections, each
+preceded by the literal heading on its own line. If a section has no
+content, write "None".
+
+1. Primary Request and Intent
+   - What the user ultimately wants, in their own framing.
+
+2. Key Technical Concepts
+   - Libraries, frameworks, architectural patterns referenced.
+
+3. Files and Code Sections
+   - Files read, written, or discussed. Include full paths and a one-line note.
+
+4. Errors and Fixes
+   - Bugs encountered and how they were resolved.
+
+5. Problem Solving
+   - Non-trivial debugging or design decisions.
+
+6. All User Messages
+   - Every user message, verbatim, in order. Do not summarize here.
+
+7. Pending Tasks
+   - Work that was planned but not yet completed.
+
+8. Current Work
+   - What was being actively worked on when the summary was taken.
+
+9. Optional Next Step
+   - The single most natural next action, if obvious.`;
+export async function compactMessagesWithLLM(messages, options) {
+    const keepRecentTurns = options.keepRecentTurns ?? 2;
+    const { leading, body } = splitLeadingContext(messages);
+    // Replace semantics: prior summaries (any form) are folded into the new
+    // summary as INPUT (the LLM merges them semantically) and removed.
+    const priorSummaries = body.filter(isCompactionSummaryMessage);
+    const bodyMessages = body.filter((m) => !isCompactionSummaryMessage(m));
+    const turnStartIndexes = bodyMessages
+        .map((m, i) => (isRealUserMessage(m) ? i : -1))
+        .filter((i) => i >= 0);
+    if (turnStartIndexes.length <= keepRecentTurns) {
+        return { compacted: false };
+    }
+    const keepStartIndex = turnStartIndexes[Math.max(0, turnStartIndexes.length - keepRecentTurns)];
+    if (keepStartIndex <= 0) {
+        return { compacted: false };
+    }
+    const oldMessages = bodyMessages.slice(0, keepStartIndex);
+    const keptMessages = bodyMessages.slice(keepStartIndex);
+    // Pin the original instruction verbatim (P0.5: this path used to lack the
+    // pin the heuristic and llm-compactor paths already had).
+    const pinnedIndex = findFirstRealUserIndex(oldMessages);
+    const pinnedMessage = pinnedIndex >= 0 ? oldMessages[pinnedIndex] : undefined;
+    // File blocks are stripped from prior summaries before summarization: the
+    // deterministic merge below owns the file lists end to end.
+    const summarizable = [
+        ...priorSummaries.map((m) => ({
+            role: "user",
+            content: `[Prior compaction summary]\n${stripFileBlocks(messageText(m))}`,
+        })),
+        ...oldMessages.filter((_, index) => index !== pinnedIndex),
+    ];
+    const fileOps = collectCompactionFileOps(oldMessages, priorSummaries);
+    let summary;
+    try {
+        summary = await generateSummary(summarizable, options);
+    }
+    catch {
+        return compactMessagesHeuristic(messages, { keepRecentTurns, maxSummaryItems: options.maxSummaryItems });
+    }
+    // Models quote their input, and the transcript can contain projected
+    // reminder blocks; this summary is persisted, so scrub markup first.
+    summary = sanitizeInternalReminderBlocks(summary).trim();
+    if (!summary) {
+        return compactMessagesHeuristic(messages, { keepRecentTurns, maxSummaryItems: options.maxSummaryItems });
+    }
+    const summaryWithFiles = appendFileBlocks(summary, fileOps);
+    return {
+        compacted: true,
+        summary: summaryWithFiles,
+        messages: [
+            ...leading,
+            ...(pinnedMessage ? [clonePinnedUserMessage(pinnedMessage)] : []),
+            buildCompactionSummaryMessage(summaryWithFiles),
+            ...keptMessages,
+        ],
+        droppedEntries: oldMessages.length,
+    };
+}
+/**
+ * Build the two-message prompt that asks the model for a 9-section summary of
+ * `oldMessages`. Shared by the non-streaming overflow path (`generateSummary`)
+ * and the streaming manual `/compact` path (`Agent.summarizeForCompaction`).
+ */
+export function buildCompactionPromptMessages(oldMessages, userContext) {
+    const transcript = serializeTranscript(oldMessages);
+    const preservationNote = userContext?.trim()
+        ? `\n\nUser-provided context for this compaction:\n${userContext.trim()}\n\nIncorporate this context prominently in the relevant sections.`
+        : "";
+    return [
+        { role: "system", content: COMPACT_SYSTEM_PROMPT },
+        {
+            role: "user",
+            content: `Conversation to summarize:\n\n${transcript}\n\n---\n\n${COMPACT_INSTRUCTIONS}${preservationNote}`,
+        },
+    ];
+}
+async function generateSummary(oldMessages, options) {
+    const messages = buildCompactionPromptMessages(oldMessages);
+    return options.provider.complete(messages, {
+        model: options.model,
+        temperature: 0.2,
+        thinkingLevel: options.thinkingLevel ?? "off",
+    });
+}
+export function serializeTranscript(messages) {
+    const lines = [];
+    for (const message of messages) {
+        // Manual /compact receives raw history, unlike the automatic path which
+        // first folds summary carriers into user messages. Keep those summaries,
+        // but do not turn ordinary system/meta reminders into durable history.
+        if (isCompactionSummaryMessage(message)) {
+            lines.push(`[Prior compaction summary] ${messageText(message)}`);
+            continue;
+        }
+        switch (message.role) {
+            case "user":
+                lines.push(`[user] ${contentToText(message.content)}`);
+                break;
+            case "assistant":
+                if (message.content)
+                    lines.push(`[assistant] ${message.content}`);
+                for (const toolCall of message.toolCalls ?? []) {
+                    lines.push(`[assistant tool_call] ${toolCall.name}(${toolCall.arguments})`);
+                }
+                break;
+            case "tool":
+                lines.push(`[tool] ${truncate(message.content, 800)}`);
+                break;
+            case "system":
+            case "meta":
+                break;
+        }
+    }
+    return lines.join("\n");
+}
+function contentToText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .filter((p) => p.type === "text")
+        .map((p) => p.text)
+        .join(" ");
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}

package/dist/context/compact.d.ts

@@ -0,0 +1,124 @@
+import type { Message } from "../types.js";
+import type { SessionLogEntry } from "../session-types.js";
+import { type CompactionFileOps } from "./compaction-files.js";
+/**
+ * Compaction must never summarize away what the user actually asked for:
+ * requirements that appear late in a long instruction ("commit when done",
+ * "write the report in French") would otherwise vanish once the heuristic
+ * summary truncates the goal line. Messages larger than this cap are pinned
+ * in truncated form (e.g. a pasted megabyte of logs as the opening message).
+ */
+export declare const PINNED_INSTRUCTION_MAX_CHARS = 8192;
+export declare const COMPACTION_SUMMARY_PREFIX = "Previous conversation summary:";
+export declare const SUBTURN_SUMMARY_PREFIX = "Earlier in this turn (compacted to free context):";
+export declare function messageText(message: Message): string;
+/**
+ * Identity check for compaction summaries across every form they can take:
+ * the first-class meta form, the legacy raw-system form, and the projected
+ * user-role internal-block forms (the resident path rewrites projections back
+ * into history, so role/position are not conserved).
+ */
+export declare function isCompactionSummaryMessage(message: Message): boolean;
+/** A message the user actually typed (not a projected reminder, not a summary). */
+export declare function isRealUserMessage(message: Message): boolean;
+/**
+ * Split history into the leading system/meta context prefix (system prompt,
+ * startup reminders) and the conversational body. Positional, mirroring the
+ * projector's leading-prefix semantics: mid-history system/meta messages
+ * belong to the body and are foldable — preserving them by role forever is
+ * how stale reminders and relocated summaries used to pile up at the head.
+ */
+export declare function splitLeadingContext(messages: Message[]): {
+    leading: Message[];
+    body: Message[];
+};
+/** Index of the first message the user actually wrote. */
+export declare function findFirstRealUserIndex(messages: Message[]): number;
+/**
+ * Clone a message for pinning; oversized content is truncated rather than
+ * losing the pin entirely (P0.5: a truncated original beats a 140-char
+ * summary line).
+ */
+export declare function clonePinnedUserMessage(message: Message): Message;
+export declare function buildCompactionSummaryMessage(summary: string): Message;
+export interface CompactOptions {
+    keepRecentTurns?: number;
+    maxSummaryItems?: number;
+}
+export interface CompactResult {
+    compacted: boolean;
+    summary?: string;
+    entries?: SessionLogEntry[];
+    messages?: Message[];
+    /** Original messages the new summary replaces (prior summary carriers
+     * plus the evicted body) — the exact set an external summarizer should
+     * condense. Kept-verbatim messages are excluded so they are not duplicated
+     * into the summary. */
+    evictedMessages?: Message[];
+    /** Index in `messages` of the one summary that stands for `evictedMessages`.
+     * Other summaries in `messages` cover different history and must survive. */
+    summaryIndex?: number;
+    droppedEntries?: number;
+}
+/**
+ * The split of a session log into (metadata, old-to-summarize, kept-verbatim)
+ * when it is large enough to compact. `compactable: false` means there aren't
+ * enough turns past the last summary to bother.
+ *
+ * Extracted so callers that supply their OWN summary (e.g. the LLM-backed
+ * manual `/compact`) can reuse the exact same turn-boundary logic instead of
+ * forking it. `compactSessionEntries` is just this plan + a heuristic summary.
+ */
+export type SessionCompactionPlan = {
+    compactable: false;
+} | {
+    compactable: true;
+    metadataEntries: SessionLogEntry[];
+    oldEntries: SessionLogEntry[];
+    keptEntries: SessionLogEntry[];
+};
+export declare function planSessionCompaction(entries: SessionLogEntry[], options?: CompactOptions): SessionCompactionPlan;
+/**
+ * Cumulative file ops for a compaction: the blocks prior summaries carried,
+ * unioned with the ops found in the messages being evicted now. Every
+ * compaction path — LLM, heuristic, sub-turn, session-entry — must thread
+ * this through, or the "cumulative" record resets on that path.
+ */
+export declare function collectCompactionFileOps(evicted: Message[], priorSummaries: Message[]): CompactionFileOps;
+/**
+ * Assemble the post-compaction entry list from a plan and a (possibly
+ * LLM-generated) summary string. The summary entry is keyed off the full
+ * original `entries` so its id never collides with a prior summary.
+ */
+export declare function buildCompactedEntries(entries: SessionLogEntry[], plan: Extract<SessionCompactionPlan, {
+    compactable: true;
+}>, summary: string): SessionLogEntry[];
+/** Flatten a plan's old entries into messages for an external summarizer. */
+export declare function planOldMessages(plan: Extract<SessionCompactionPlan, {
+    compactable: true;
+}>): Message[];
+export declare function compactSessionEntries(entries: SessionLogEntry[], options?: CompactOptions): CompactResult;
+export declare function compactMessages(messages: Message[], options?: CompactOptions): CompactResult;
+/**
+ * Sub-turn compaction.
+ *
+ * When the active user turn has accumulated many (assistant + tool-result) groups
+ * — typically a single "look at this project" prompt that triggers a dozen file
+ * reads — multi-turn compactMessages above is a no-op (there's only one user turn
+ * to summarize). This variant operates one level finer: it groups messages inside
+ * the last user turn by assistant message, keeps the most recent K groups intact,
+ * and replaces the older ones with a synthetic system message that names the tools
+ * called and files inspected.
+ *
+ * Constraints honored:
+ * - Older groups are dropped WHOLE (assistant + its tool results). Dropping just
+ *   the tool results would leave orphan tool_calls; repairToolCallChains would
+ *   then synthesize "[no result captured]" placeholders, undoing the win.
+ * - Pre-turn content (earlier user turns) is left untouched — that's the
+ *   multi-turn compactor's territory.
+ */
+export interface SubTurnCompactOptions {
+    keepRecentGroups?: number;
+    maxSummaryItems?: number;
+}
+export declare function compactCurrentTurnToolGroups(messages: Message[], options?: SubTurnCompactOptions): CompactResult;