@bubblebrain-ai/bubble 0.0.40 → 0.0.42

package/dist/agent/internal-reminder-sanitizer.d.ts

@@ -1,4 +1,12 @@
 import type { AssistantProviderMetadata } from "../types.js";
+/** Prefix shared by every internal reminder/context block this module emits. */
+export declare const INTERNAL_BLOCK_PREFIX = "<bubble_internal_";
+/**
+ * True when the text is an internal reminder/context block (e.g. a meta
+ * message that the projector re-rolled into user role) rather than something
+ * the user actually typed.
+ */
+export declare function isInternalBlockContent(text: string): boolean;
 export declare function formatInternalReminderBlock(kind: string, content: string): string;
 export declare function formatInternalContextBlock(kind: string, content: string): string;
 export declare function sanitizeInternalReminderBlocks(text: string): string;

package/dist/agent/internal-reminder-sanitizer.js

@@ -27,6 +27,16 @@ const LEGACY_REMINDER_END_PHRASES = [
     "- Skip the \"investigate the codebase\" step that applies to larger changes.",
     "Do not put the final answer only in hidden reasoning.",
 ];
+/** Prefix shared by every internal reminder/context block this module emits. */
+export const INTERNAL_BLOCK_PREFIX = "<bubble_internal_";
+/**
+ * True when the text is an internal reminder/context block (e.g. a meta
+ * message that the projector re-rolled into user role) rather than something
+ * the user actually typed.
+ */
+export function isInternalBlockContent(text) {
+    return text.trimStart().startsWith(INTERNAL_BLOCK_PREFIX);
+}
 export function formatInternalReminderBlock(kind, content) {
     return formatInternalBlock("reminder", kind, content);
 }

package/dist/agent.d.ts

@@ -175,6 +175,7 @@ export declare class Agent {
     private readonly subagentUpdateWakers;
     private lastInputTokens;
     private lastAnchorMessageCount;
+    private compactionStats;
     constructor(options: AgentOptions);
     /**
      * Re-inject the deferred-tools advertisement. Hosts that reassign
@@ -226,6 +227,7 @@ export declare class Agent {
     private getActiveToolEntries;
     injectSystemReminder(content: string): void;
     injectModeReminder(): void;
+    get role(): "parent" | "subagent";
     get model(): string;
     set model(value: string);
     get providerId(): string;
@@ -256,6 +258,13 @@ export declare class Agent {
     private recoverFromOverflow;
     compactResidentHistory(): void;
     private maybeCompactWithLLM;
+    /** Snapshot of how often each compaction path rewrote history this run. */
+    getCompactionStats(): {
+        resident: number;
+        llm: number;
+        overflow: number;
+        droppedMessages: number;
+    };
     /**
      * Stream a 9-section handoff summary of `oldMessages` from the session model.
      * Powers the manual `/compact` command: streaming (rather than `complete()`)

package/dist/agent.js

@@ -172,6 +172,12 @@ export class Agent {
     subagentUpdateWakers = new Set();
     lastInputTokens = null;
     lastAnchorMessageCount = null;
+    // How often each compaction path actually rewrote history this run.
+    // Surfaced via getCompactionStats() for print-mode telemetry: without it,
+    // "did the model ever stop seeing the original instruction?" is
+    // unanswerable from the outside (only counts real compactions, not
+    // byte-saving projection rewrites).
+    compactionStats = { resident: 0, llm: 0, overflow: 0, droppedMessages: 0 };
     constructor(options) {
         this.provider = options.provider;
         this.sessionID = options.sessionID;
@@ -422,6 +428,9 @@ export class Agent {
         }
         this.injectSystemReminder(reminder);
     }
+    get role() {
+        return this.agentRole;
+    }
     get model() {
         return this._model;
     }
@@ -992,6 +1001,9 @@ export class Agent {
                     }
                     const droppedMessages = await this.recoverFromOverflow(consecutiveOverflowRecoveries);
                     consecutiveOverflowRecoveries += 1;
+                    this.compactionStats.overflow += 1;
+                    this.compactionStats.droppedMessages += droppedMessages;
+                    traceEvent("compaction_fired", { path: "overflow", droppedMessages });
                     yield emit({ type: "context_recovered", droppedMessages, reason: "overflow" });
                     continue;
                 }
@@ -1507,10 +1519,16 @@ export class Agent {
             this.lastInputTokens = null;
             this.lastAnchorMessageCount = null;
             this.fileStateTracker?.invalidateReadHistory();
+            this.compactionStats.llm += 1;
+            traceEvent("compaction_fired", { path: "llm" });
         }
         // If LLM compaction failed for any reason, leave this.messages alone —
         // the projector's algorithmic budgeted-mode passes will still try.
     }
+    /** Snapshot of how often each compaction path rewrote history this run. */
+    getCompactionStats() {
+        return { ...this.compactionStats };
+    }
     /**
      * Stream a 9-section handoff summary of `oldMessages` from the session model.
      * Powers the manual `/compact` command: streaming (rather than `complete()`)
@@ -2537,6 +2555,8 @@ export class Agent {
             const compacted = compactMessages(candidate, { keepRecentTurns });
             if (compacted.compacted && compacted.messages) {
                 candidate = compacted.messages;
+                this.compactionStats.resident += 1;
+                traceEvent("compaction_fired", { path: "resident", droppedEntries: compacted.droppedEntries });
             }
         }
         const afterChars = estimateResidentChars(candidate);

package/dist/context/compact.d.ts

@@ -1,5 +1,20 @@
 import type { Message } from "../types.js";
 import type { SessionLogEntry } from "../session-types.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 exempt
+ * from pinning (e.g. a pasted megabyte of logs as the opening message) —
+ * summarization is the lesser evil there.
+ */
+export declare const PINNED_INSTRUCTION_MAX_CHARS = 8192;
+/**
+ * Index of the first message the user actually wrote: user-role, not an
+ * internal reminder/context block re-rolled into user role by the projector,
+ * and small enough to keep verbatim.
+ */
+export declare function findFirstRealUserIndex(messages: Message[]): number;
 export interface CompactOptions {
     keepRecentTurns?: number;
     maxSummaryItems?: number;

package/dist/context/compact.js

@@ -1,3 +1,43 @@
+import { isInternalBlockContent } from "../agent/internal-reminder-sanitizer.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 exempt
+ * from pinning (e.g. a pasted megabyte of logs as the opening message) —
+ * summarization is the lesser evil there.
+ */
+export const PINNED_INSTRUCTION_MAX_CHARS = 8192;
+function userMessageText(message) {
+    if (typeof message.content === "string")
+        return message.content;
+    if (Array.isArray(message.content)) {
+        return message.content
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join(" ");
+    }
+    return "";
+}
+/**
+ * Index of the first message the user actually wrote: user-role, not an
+ * internal reminder/context block re-rolled into user role by the projector,
+ * and small enough to keep verbatim.
+ */
+export function findFirstRealUserIndex(messages) {
+    for (let index = 0; index < messages.length; index++) {
+        const message = messages[index];
+        if (message.role !== "user")
+            continue;
+        const text = userMessageText(message);
+        if (!text.trim() || isInternalBlockContent(text))
+            continue;
+        if (text.length > PINNED_INSTRUCTION_MAX_CHARS)
+            return -1;
+        return index;
+    }
+    return -1;
+}
 export function planSessionCompaction(entries, options = {}) {
     const keepRecentTurns = options.keepRecentTurns ?? 2;
     const metadataEntries = entries.filter((entry) => entry.type === "metadata");
@@ -74,12 +114,20 @@ export function compactMessages(messages, options = {}) {
     }
     const oldMessages = conversationalMessages.slice(0, keepStartIndex);
     const keptMessages = conversationalMessages.slice(keepStartIndex);
-    const summary = buildMessageSummary(oldMessages, maxSummaryItems);
+    // Pin the original instruction: it stays verbatim above the summary instead
+    // of being crushed into the summary's 140-char goal line.
+    const pinnedIndex = findFirstRealUserIndex(oldMessages);
+    const pinnedMessage = pinnedIndex >= 0 ? oldMessages[pinnedIndex] : undefined;
+    const summaryInput = pinnedIndex >= 0
+        ? oldMessages.filter((_, index) => index !== pinnedIndex)
+        : oldMessages;
+    const summary = buildMessageSummary(summaryInput, maxSummaryItems);
     if (!summary) {
         return { compacted: false };
     }
     const compactedMessages = [
         ...preservedContextMessages.map((message) => cloneMessage(message)),
+        ...(pinnedMessage ? [cloneMessage(pinnedMessage)] : []),
         {
             role: "system",
             content: `Previous conversation summary:\n${summary}`,
@@ -90,7 +138,7 @@ export function compactMessages(messages, options = {}) {
         compacted: true,
         summary,
         messages: compactedMessages,
-        droppedEntries: oldMessages.length,
+        droppedEntries: summaryInput.length,
     };
 }
 export function compactCurrentTurnToolGroups(messages, options = {}) {

package/dist/context/llm-compactor.js

@@ -10,6 +10,7 @@
 // Failure modes are explicit: returns { compacted: false, reason } so the
 // caller can fall back to algorithmic compaction without an exception.
 import { estimateContextTokens } from "./budget.js";
+import { findFirstRealUserIndex } from "./compact.js";
 export const LLM_COMPACTION_PROMPT = `You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
 
 Include:
@@ -40,9 +41,21 @@ export async function compactWithLLM(messages, options) {
     //   priorTurns:   everything from earlier user turns (multi-turn case)
     //   lastUser:     the user's current ask (always kept verbatim)
     //   currentTurn:  the assistant + tool groups produced in response so far
+    //
+    // The FIRST real user message (the original instruction) is pinned verbatim
+    // too: after meta reminders get re-rolled into user role by the projector,
+    // "last user message" often points at a reminder, not the instruction — and
+    // late requirements in a long instruction must survive compaction.
     const priorTurns = body.slice(0, lastUserIndex);
     const lastUser = body[lastUserIndex];
     const currentTurn = body.slice(lastUserIndex + 1);
+    const firstRealUserIndex = findFirstRealUserIndex(body);
+    const pinnedFirstUser = firstRealUserIndex >= 0 && firstRealUserIndex < lastUserIndex
+        ? body[firstRealUserIndex]
+        : undefined;
+    const summarizablePriorTurns = pinnedFirstUser
+        ? priorTurns.filter((message) => message !== pinnedFirstUser)
+        : priorTurns;
     const groups = [];
     let active = null;
     for (const msg of currentTurn) {
@@ -61,9 +74,10 @@ export async function compactWithLLM(messages, options) {
     const evictedGroups = groups.slice(0, groups.length - keptGroupCount);
     const keptGroups = groups.slice(groups.length - keptGroupCount);
     // What we'll send to the model to summarize: prior turns + the older groups
-    // in the current turn (everything we're about to evict).
+    // in the current turn (everything we're about to evict). The pinned first
+    // instruction is excluded — it survives verbatim, not as summary fodder.
     const toSummarize = [
-        ...priorTurns,
+        ...summarizablePriorTurns,
         ...evictedGroups.flatMap((g) => [g.assistant, ...g.toolResults]),
     ];
     if (toSummarize.length === 0) {
@@ -105,6 +119,7 @@ export async function compactWithLLM(messages, options) {
     }
     const compacted = [
         ...preserved.map(cloneMessage),
+        ...(pinnedFirstUser ? [cloneMessage(pinnedFirstUser)] : []),
         {
             role: "user",
             content: `${LLM_SUMMARY_PREFIX}\n${summaryText.trim()}`,

package/dist/main.js

@@ -616,6 +616,7 @@ async function main() {
                     process.stdout.write(formatPrintJson({
                         summary: collector.summary(),
                         sessionId: printSessionId,
+                        compaction: agent.getCompactionStats(),
                     }) + "\n");
                 }
                 else {
@@ -631,6 +632,7 @@ async function main() {
                     message: error instanceof Error ? error.message : String(error),
                     summary: collector.summary(),
                     sessionId: printSessionId,
+                    compaction: agent.getCompactionStats(),
                 }) + "\n");
                 process.exitCode = 1;
             }

package/dist/orchestrator/default-hooks.js

@@ -4,7 +4,7 @@ import { EvidenceTracker } from "../agent/evidence-tracker.js";
 import { ExecutionGovernor } from "../agent/execution-governor.js";
 import { DiscoveryBarrier } from "../agent/discovery-barrier.js";
 import { arbitrateToolCall } from "../agent/tool-arbiter.js";
-import { buildEditRetryEscalationReminder, buildSmallTaskHint, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
+import { buildCompletionSelfCheckReminder, buildEditRetryEscalationReminder, buildSmallTaskHint, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
 import { largeImplementationTaskReminder, orchestrationRequestReminder, reminderForTaskType, userNamedModelReminder } from "../prompt/task-reminders.js";
 import { formatCoverageSummary, resolveWorkflowPhase } from "./workflow.js";
 import { resolve as resolvePath } from "node:path";
@@ -220,9 +220,33 @@ export function createDefaultHooks() {
                 }
                 // Verification reminders intentionally removed. See afterToolCall.
             },
-            afterTurn() {
+            afterTurn(ctx) {
                 // Verification force-continuation removed. The model decides whether
                 // verification is meaningful for the task, per the system prompt.
+                //
+                // Completion self-check gate: when a run that changed code is about
+                // to end (this hook only runs on final, no-tool-call turns), remind
+                // the model ONCE to re-read the original request before finishing.
+                // Unlike the removed verification gate it never repeats — the model
+                // is explicitly told a confirming final answer ends the run — so the
+                // "prove it" spiral that killed the old design cannot start.
+                if (ctx.state.completionGateFired)
+                    return;
+                if (!ctx.state.codeChanged)
+                    return;
+                // Tools are frozen: the model could not act on anything the check
+                // surfaces, so another turn is pure token burn.
+                if (ctx.state.forceTextOnlyReason)
+                    return;
+                // Subagents hand off to a parent that does its own closing pass, and
+                // worktree profiles explicitly forbid the very actions a completion
+                // check would suggest.
+                if (ctx.agent.role === "subagent")
+                    return;
+                ctx.state.completionGateFired = true;
+                ctx.state.forceContinuationReason = "completion_self_check";
+                ctx.queueReminder(buildCompletionSelfCheckReminder());
+                traceEvent("completion_gate_fired", { turnCount: ctx.state.turnCount });
             },
         },
     ];

package/dist/orchestrator/hooks.d.ts

@@ -16,6 +16,8 @@ export interface TurnHookState {
     forceTextOnlyReason?: string;
     forceContinuationReason?: string;
     codeChanged?: boolean;
+    /** Completion self-check gate already fired this run (fires at most once). */
+    completionGateFired?: boolean;
     smallTaskHintSent?: boolean;
     recentEditFailures?: string[];
     editNoMatchReminderPaths?: string[];

package/dist/print-output.d.ts

@@ -42,13 +42,26 @@ export declare class PrintRunCollector {
     private addUsage;
     summary(): PrintRunSummary;
 }
+/**
+ * Per-path counts of context compactions during the run. Lets benchmark
+ * harnesses correlate outcomes with "did the model ever lose sight of the
+ * full history" without access to the in-container session files.
+ */
+export interface PrintCompactionStats {
+    resident: number;
+    llm: number;
+    overflow: number;
+    droppedMessages: number;
+}
 export declare function formatPrintJson(input: {
     summary: PrintRunSummary;
     sessionId?: string;
     stopReason?: "end_turn" | "error" | "cancelled";
+    compaction?: PrintCompactionStats;
 }): string;
 export declare function formatPrintJsonError(input: {
     message: string;
     summary?: PrintRunSummary;
     sessionId?: string;
+    compaction?: PrintCompactionStats;
 }): string;

package/dist/print-output.js

@@ -83,6 +83,7 @@ export function formatPrintJson(input) {
         num_tool_calls: input.summary.num_tool_calls,
         usage: input.summary.usage,
         usage_reported: input.summary.usage_reported,
+        ...(input.compaction ? { compaction: input.compaction } : {}),
     });
 }
 export function formatPrintJsonError(input) {
@@ -99,5 +100,6 @@ export function formatPrintJsonError(input) {
                 usage: input.summary.usage,
             }
             : {}),
+        ...(input.compaction ? { compaction: input.compaction } : {}),
     });
 }

package/dist/prompt/reminders.d.ts

@@ -23,6 +23,7 @@ export declare function buildInvestigationReminder(): string;
 export declare function buildLoopWarningReminder(reason: string): string;
 export declare function buildSearchFreezeReminder(reason: string): string;
 export declare function buildExplorationFreezeReminder(reason: string): string;
+export declare function buildCompletionSelfCheckReminder(): string;
 export declare function buildToolFreezeReminder(reason: string): string;
 export declare function buildWorkflowPhaseReminder(input: {
     phase: "investigate" | "correlate" | "conclude";

package/dist/prompt/reminders.js

@@ -119,6 +119,13 @@ Choose one of:
 3. If files were already changed, run the narrowest meaningful verification or finish with the result.
 `);
 }
+export function buildCompletionSelfCheckReminder() {
+    return wrapInSystemReminder(`
+You appear to be finishing. Before giving your final answer, re-read the user's original request in this conversation and check whether any explicit requirement in it remains unfulfilled — including requirements about how the work should be delivered or reported, not only whether the implementation works.
+
+If something is missing, complete it now. If everything is done, give your final answer directly — do not repeat this check or re-verify work you have already verified.
+`);
+}
 export function buildToolFreezeReminder(reason) {
     return wrapInSystemReminder(`
 CRITICAL - MAXIMUM STEPS REACHED

package/dist/prompt/runtime.js

@@ -11,6 +11,7 @@ const defaultGuidelines = [
     "Prefer structured tools (glob, grep, read) over bash for search and inspection. Do not repeat a near-identical search or re-read the same file unless new evidence changes the question.",
     "If a tool fails, diagnose the error before switching tactics. Do not retry the identical call with identical arguments. After two equivalent failures, switch approach — re-read the file, use a different tool, rewrite the whole file with write, or ask the user.",
     "Before reporting a task complete, verify it works when verification is meaningful and cheap — run the existing test, execute the script, check the output. If no test exists, the change is purely declarative (static HTML/markdown/config), or running the code is not practical, state that explicitly rather than inventing a verification step. Do not write throwaway validation scripts to prove correctness; if there is no real check to run, report the change and stop.",
+    "Before declaring a task complete, re-read the user's original request and verify that every explicit requirement in it — about both the result and the process — has been fulfilled, not only that the implementation works.",
 ];
 export function buildRuntimePrompt(options = {}) {
     const guidelines = dedupe(defaultGuidelines, options.guidelines ?? []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bubblebrain-ai/bubble",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "description": "A terminal coding agent",
   "type": "module",
   "engines": {