@vellumai/assistant 0.8.1 → 0.8.3

package/src/context/window-manager.ts

@@ -1,247 +1,46 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
+/**
+ * Context window manager — the surface the rest of the daemon talks to
+ * when it needs to know whether and how to compact a conversation.
+ *
+ * The actual compaction work is delegated to {@link runAssistantDrivenCompaction}
+ * in `./compactor.js`, which hands the model the full conversation plus a
+ * user-role instruction message and lets the assistant write its own
+ * summary and choose its own cut point.
+ *
+ * This module retains a small set of legacy exports — `CONTEXT_SUMMARY_MARKER`,
+ * `createContextSummaryMessage`, `getSummaryFromContextMessage` — because
+ * conversation reload, fork inheritance, and Slack chronological-context
+ * assembly all detect a previously-produced summary via the marker. The
+ * marker is wrapped around the assistant-role memory message we emit on
+ * successful compaction so those code paths keep working unchanged.
+ */
+import { getConfig } from "../config/loader.js";
+import type { CompactionConfig } from "../config/schemas/compaction.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { ContextWindowConfig } from "../config/types.js";
 import type {
   ContentBlock,
-  ImageContent,
   Message,
   Provider,
+  ToolDefinition,
 } from "../providers/types.js";
-import { resolveBundledDir } from "../util/bundled-asset.js";
 import { getLogger } from "../util/logger.js";
-import { safeStringSlice } from "../util/unicode.js";
 import {
-  estimateContentBlockTokens,
-  estimatePromptTokens,
-  estimateTextTokens,
-} from "./token-estimator.js";
-import { truncateToolResultsAcrossHistory } from "./tool-result-truncation.js";
+  type CompactionRunArgs,
+  runAssistantDrivenCompaction,
+} from "./compactor.js";
+import { estimatePromptTokens } from "./token-estimator.js";
 
 const log = getLogger("context-window");
 
 export const CONTEXT_SUMMARY_MARKER = "<context_summary>";
-const CONVERSATION_SUMMARY_CALL_SITE: LLMCallSite = "conversationSummarization";
-const MAX_BLOCK_PREVIEW_CHARS = 3000;
-const MAX_FALLBACK_SUMMARY_CHARS = 12000;
-const COMPACTION_COOLDOWN_MS = 2 * 60 * 1000;
-const MIN_GAIN_TOKENS_DURING_COOLDOWN = 1200;
-const SEVERE_PRESSURE_RATIO = 0.95;
-const COMPACTION_TOOL_RESULT_MAX_CHARS = 6_000;
-const MIN_COMPACTABLE_PERSISTED_MESSAGES = 2;
+const CONTEXT_SUMMARY_CLOSE = "</context_summary>";
 const INTERNAL_CONTEXT_SUMMARY_MESSAGES = new WeakSet<Message>();
 
-/**
- * Hard cap on the verbatim tail-anchor block we splice into the
- * post-compaction summary message (see `extractTailAssistantText`). 1500
- * chars (~375 tokens) covers a few paragraphs of recent assistant
- * narration without bloating the summary. When the tail exceeds this
- * size we keep the END (most recent text), since "next step" / "now I'll
- * …" statements typically live at the end of the assistant's last text
- * block and that's the part the post-compaction model needs most.
- */
-const TAIL_ANCHOR_MAX_CHARS = 1500;
-const TAIL_ANCHOR_OPEN_TAG = "<verbatim_tail>";
-const TAIL_ANCHOR_CLOSE_TAG = "</verbatim_tail>";
-
-/**
- * When the existing summary is this fraction or more of the per-summary
- * token budget, inject a "compress older content aggressively" instruction
- * so incremental-update passes don't let the summary grow unboundedly.
- */
-const SUMMARY_COMPRESSION_PRESSURE_RATIO = 0.6;
-
-/**
- * Text-block prefixes that persist in live history (for prefix-caching
- * stability and model grounding) but pollute the summarizer's view of the
- * actual conversation. These blocks are system-metadata attached to user
- * turns — memory injections, turn context, workspace hints, etc. They are
- * stripped ONLY from the messages fed to the summarization LLM call. Live
- * history is never mutated, so prefix caching is preserved.
- *
- * This list intentionally overlaps with `RUNTIME_INJECTION_PREFIXES` in
- * `conversation-runtime-assembly.ts`. That list governs in-flight turn
- * assembly via pure prefix matching; this one governs compaction input.
- * Keep the two lists in sync when a new injection type is added.
- *
- * Compaction strip coverage is two-tier: this prefix list catches
- * internal-vocabulary tags and any tag carrying the `__injected`
- * attribute, while `COMPACTION_ONLY_WRAPPED_STRIP_TAGS` below matches
- * ambiguous bare-tag blocks that are shaped like a runtime-emitted
- * open/close wrap. A new ambiguous tag added upstream needs to be
- * evaluated against both tiers — internal-vocabulary names go here,
- * and names whose bare form collides with ordinary English
- * (`<memory>`, `<workspace>`, `<knowledge_base>`, `<pkb>`,
- * `<system_reminder>`) go in the wrapped-strip list so user prose
- * mentioning the tag is preserved.
- */
-const COMPACTION_ONLY_STRIP_PREFIXES = [
-  "<memory __injected>",
-  "<memory_image __injected>",
-  "</memory_image>",
-  "<memory_context __injected>",
-  "<turn_context>",
-  "<channel_turn_context>",
-  "<guardian_context>",
-  "<inbound_actor_context>",
-  "<interface_turn_context>",
-  "<workspace_top_level>",
-  "<now_scratchpad>",
-  "<NOW.md Always keep this up to date",
-  "<active_thread>",
-  "<active_subagents>",
-  "<active_workspace>",
-  "<active_dynamic_page>",
-  "<channel_capabilities>",
-  "<channel_command_context>",
-  "<voice_call_control>",
-  "<transport_hints>",
-  "<system_notice>",
-  "<non_interactive_context>",
-  "<temporal_context>",
-];
-
-/**
- * Tags whose bare form (`<tag>`) is common English vocabulary or markup a
- * user might legitimately type in prose. For these we only strip a text
- * block if it is shaped exactly like a runtime injection: starts with
- * `<tag>\n` and ends with `</tag>`. This bare-tag wrapped shape
- * (e.g. `<memory>\n...\n</memory>`) appears in persisted history
- * alongside the `__injected`-attributed variants, which the prefix list
- * above already catches via `<memory __injected>`. A user who mentions
- * `<memory>` in a sentence or inlines `<workspace>...</workspace>` within
- * other prose will not match this shape.
- */
-const COMPACTION_ONLY_WRAPPED_STRIP_TAGS = [
-  "memory",
-  "memory_context",
-  "workspace",
-  "knowledge_base",
-  "pkb",
-  "system_reminder",
-];
-
-function isCompactionInjectedBlock(text: string): boolean {
-  if (COMPACTION_ONLY_STRIP_PREFIXES.some((p) => text.startsWith(p))) {
-    return true;
-  }
-  return COMPACTION_ONLY_WRAPPED_STRIP_TAGS.some(
-    (tag) => text.startsWith(`<${tag}>\n`) && text.endsWith(`</${tag}>`),
-  );
-}
-
-/**
- * Remove text blocks that look like runtime injections from user messages.
- * Non-text blocks (images, tool_use, tool_result, etc.) are untouched.
- * Empty messages (every block filtered out) are dropped from the output.
- *
- * Used only on the `compactableMessages` slice right before it is
- * serialized for the summarization LLM — the caller's original message
- * array is never mutated.
- */
-export function stripCompactionOnlyInjections(messages: Message[]): Message[] {
-  return messages
-    .map((message) => {
-      if (message.role !== "user") return message;
-      const nextContent = message.content.filter((block) => {
-        if (block.type !== "text") return true;
-        return !isCompactionInjectedBlock(block.text);
-      });
-      if (nextContent.length === message.content.length) return message;
-      if (nextContent.length === 0) return null;
-      return { ...message, content: nextContent };
-    })
-    .filter(
-      (message): message is NonNullable<typeof message> => message != null,
-    );
-}
-
-/**
- * Load the compaction summary system prompt from the bundled markdown asset.
- *
- * `resolveBundledDir` handles the compiled-binary case where the caller path
- * points to `/$bunfs/` and the asset lives next to the executable (macOS app
- * bundle `Contents/Resources/` or sibling dir). In source mode it falls back
- * to the sibling `prompts/` directory.
- */
-export function loadCompactPrompt(): string {
-  const callerDir = import.meta.dirname ?? __dirname;
-  const promptsDir = resolveBundledDir(callerDir, "prompts", "compact-prompts");
-  const promptPath = join(promptsDir, "compact.md");
-  const contents = readFileSync(promptPath, "utf-8");
-  if (contents.length === 0) {
-    throw new Error(
-      `compact.md at ${promptPath} is empty — compaction summary prompt missing`,
-    );
-  }
-  return contents;
-}
-
-/**
- * Hardcoded fallback prompt used when the bundled `compact.md` asset is
- * missing or unreadable, so the daemon can still compact conversations
- * rather than failing module import at startup.
- */
-const SUMMARY_PROMPT_FALLBACK = [
-  "You are summarizing a long conversation so that the assistant can keep working with it after older messages are dropped. Your summary will REPLACE those messages — the assistant's only access to what was said earlier will be what you write here.",
-  "",
-  "Be thorough. Capture what happened, why it mattered, what's unresolved, and what was felt. Do not compress away emotional tone, relationship context, or nuance. Keep specific details (names, numbers, file paths, commands, URLs, exact phrasings) when they might matter later.",
-  "",
-  "Target length: aim for 1500–4000 tokens. Use the upper end when the conversation is rich in decisions, relationships, emotional content, or threads that are still open. Use the lower end for short or simple task execution.",
-  "",
-  "Open with a 1–2 paragraph narrative describing what the conversation is about and where it currently stands. Then use `## ` section headers. Use these when they apply; skip sections that have nothing to say; add your own headers when something doesn't fit:",
-  "- `## What We're Working On`",
-  "- `## Decisions & Commitments`",
-  "- `## Facts Worth Remembering`",
-  "- `## Open Threads`",
-  "- `## Emotional Arc / Relationship Notes` (include when relevant)",
-  "- `## Artifacts & References`",
-  "",
-  "If an existing summary is provided, update it: merge new information in, prefer the most recent and explicit detail on conflicts, and preserve anything still unresolved or still true. Do not restart from scratch.",
-  "",
-  "Never include in the summary: content inside `<memory __injected>`, `<memory>`, `<turn_context>`, `<workspace>`, `<knowledge_base>`, `<system_reminder>`, `<now_scratchpad>`, `<NOW.md …>`, `<active_thread>`, `<channel_capabilities>`, `<transport_hints>`, `<system_notice>`, or any other angle-bracket-tagged system blocks. Tool-call boilerplate (retries, failed attempts the assistant recovered from, routine status updates) — summarize the outcome instead. Repetitive chit-chat that adds nothing.",
-  "",
-  'Thread anchors (Slack only): if the input includes a "Retained Thread References" section, each listed reply cites its parent via `→ Mxxxxxx`. If that parent appears in the Transcript, preserve its text verbatim. Omit when absent.',
-  "",
-  "Return only the summary itself in markdown — no preamble, no meta-commentary.",
-].join("\n");
-
-/**
- * Load the compact prompt with graceful fallback. If `loader` throws (missing
- * or unreadable bundled asset, partial deployment, filesystem corruption),
- * logs a warning and returns the hardcoded fallback string so module import
- * never fails. The loader is injectable for testability.
- */
-export function loadCompactPromptOrFallback(
-  loader: () => string = loadCompactPrompt,
-): string {
-  try {
-    return loader();
-  } catch (err) {
-    log.warn(
-      { err },
-      "Failed to load compact.md from bundle; using inline fallback prompt. The bundled asset may be missing or unreadable.",
-    );
-    return SUMMARY_PROMPT_FALLBACK;
-  }
-}
-
-const SUMMARY_SYSTEM_PROMPT = loadCompactPromptOrFallback();
-
-/**
- * Pattern matching a Slack-style reply tag-line's parent-alias reference.
- * The chronological renderer emits reply lines as
- * `[MM/DD/YY HH:MM @sender → Mxxxxxx]: body`, or, for edited replies,
- * `[MM/DD/YY HH:MM @sender → Mxxxxxx, edited MM/DD/YY HH:MM]: body`. The
- * character after the 6-hex parent alias is therefore `]` for a plain reply
- * or `,` for an edited one — the regex accepts either. `Mxxxxxx` is the
- * first 6 hex chars of sha256(threadTs). A retained-tail text block that
- * contains this pattern is carrying a live reference to a parent that may
- * still live in the compactable region — the summarizer needs to know about
- * it to act on the Thread-anchors clause of SUMMARY_SYSTEM_PROMPT.
- */
-const THREAD_REPLY_REFERENCE_PATTERN = /→ M[0-9a-f]{6}[,\]]/;
+// ---------------------------------------------------------------------------
+// Public types — preserved for downstream consumers (agent loop, conversation,
+// plugin pipeline, applyCompactionResult, routes/playground/force-compact).
+// ---------------------------------------------------------------------------
 
 export interface ContextWindowResult {
   messages: Message[];
@@ -263,12 +62,6 @@ export interface ContextWindowResult {
   summaryRawResponses?: unknown[];
   summaryText: string;
   reason?: string;
-  /**
-   * True when the summary LLM call threw and the local fallback produced the
-   * summary. Callers use this to distinguish provider-side summary failures
-   * from successful compactions so they can apply circuit-breaker logic
-   * without losing the fallback-compacted messages.
-   */
   summaryFailed?: boolean;
 }
 
@@ -279,41 +72,27 @@ export interface ShouldCompactResult {
 
 export interface ContextWindowCompactOptions {
   lastCompactedAt?: number;
-  /** Bypass the threshold check and force compaction. Used for context-too-large error recovery. */
+  /** Skip the auto-threshold check (used for /compact and recovery). */
   force?: boolean;
   /**
-   * Override the minimum number of recent user turns to preserve.
-   * Set to `0` for emergency recovery that can compact the entire history
-   * (except the summary message itself). When omitted, the default floor
-   * is `1` (or `8` when `conversationOriginChannel === "slack"`).
-   */
-  minKeepRecentUserTurns?: number;
-  /**
-   * Origin channel hint used when `minKeepRecentUserTurns` is omitted.
-   * Slack-originated conversations bump the default keep floor so multi-turn
-   * thread context (replies, quoted messages) is not summarized away too
-   * aggressively. Explicit `minKeepRecentUserTurns` overrides this hint.
-   */
-  conversationOriginChannel?: string;
-  /**
-   * Per-conversation inference-profile override forwarded to the summary LLM
-   * call and usage attribution.
+   * Per-conversation inference-profile override forwarded to the compaction
+   * LLM call.
    */
   overrideProfile?: string | null;
   /**
-   * Override the target input token budget used for keep-boundary
-   * projected-fit checks. Clamped to no looser than `config.targetInputTokens`
-   * — i.e. the override may only demand a *stricter* fit. Passing a looser
-   * value has no effect. Intended for forced recovery paths that need a
-   * tighter target than the default.
+   * Pre-computed token estimate from a prior {@link shouldCompact} call.
+   * Avoids a redundant tokenization pass when the caller already has one.
    */
-  targetInputTokensOverride?: number;
+  precomputedEstimate?: number;
   /**
-   * Pre-computed token estimate from a prior `shouldCompact()` call.
-   * When provided, `maybeCompact()` skips its own `estimatePromptTokens()`
-   * call, avoiding a redundant O(history) tokenization pass.
+   * Legacy fields retained for backwards compatibility with existing
+   * callers. The new assistant-driven compactor does not consume them —
+   * the model decides where to cut and what to keep — but accepting them
+   * here lets callers keep their existing call sites unchanged.
    */
-  precomputedEstimate?: number;
+  minKeepRecentUserTurns?: number;
+  conversationOriginChannel?: string;
+  targetInputTokensOverride?: number;
 }
 
 export interface ContextWindowManagerOptions {
@@ -322,36 +101,83 @@ export interface ContextWindowManagerOptions {
   config: ContextWindowConfig;
   /** Pre-computed tool token budget to include in all estimations. */
   toolTokenBudget?: number;
+  /** Conversation ID — required for image-manifest and timestamp lookups. */
+  conversationId?: string;
+  /**
+   * Optional tools resolver. The compactor passes tools to the provider on
+   * the compaction call so the cached prefix (system prompt + tools +
+   * conversation messages) matches the agent's main-turn cache key.
+   */
+  resolveTools?: () => ToolDefinition[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Summary-message helpers (used by lifecycle rehydrate + fork inheritance)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the synthetic memory message that heads a compacted conversation.
+ * Produces an `assistant`-role message wrapped in `<context_summary>` tags
+ * so reload and inheritance paths can recognize it via
+ * {@link getSummaryFromContextMessage}.
+ */
+export function createContextSummaryMessage(summary: string): Message {
+  const message: Message = {
+    role: "assistant",
+    content: [
+      {
+        type: "text",
+        text: `${CONTEXT_SUMMARY_MARKER}\n${summary}\n${CONTEXT_SUMMARY_CLOSE}`,
+      },
+    ],
+  };
+  INTERNAL_CONTEXT_SUMMARY_MESSAGES.add(message);
+  return message;
+}
+
+export function getSummaryFromContextMessage(
+  message: Message | undefined,
+): string | null {
+  if (!message) return null;
+  const text = extractText(message.content).trim();
+  if (!text.startsWith(CONTEXT_SUMMARY_MARKER)) return null;
+  if (!INTERNAL_CONTEXT_SUMMARY_MESSAGES.has(message)) return null;
+  let inner = text.slice(CONTEXT_SUMMARY_MARKER.length);
+  const closeIdx = inner.lastIndexOf(CONTEXT_SUMMARY_CLOSE);
+  if (closeIdx !== -1) inner = inner.slice(0, closeIdx);
+  return inner.trim();
 }
 
+function extractText(content: ContentBlock[]): string {
+  return content
+    .filter(
+      (b): b is Extract<ContentBlock, { type: "text" }> => b.type === "text",
+    )
+    .map((b) => b.text)
+    .join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// ContextWindowManager
+// ---------------------------------------------------------------------------
+
 export class ContextWindowManager {
   private readonly provider: Provider;
   private readonly _systemPrompt: string | (() => string);
   private config: ContextWindowConfig;
   private readonly toolTokenBudget: number;
+  private readonly conversationId: string | undefined;
+  private readonly resolveTools:
+    | (() => ToolDefinition[] | undefined)
+    | undefined;
   /**
    * Number of leading messages that are non-persisted (injected inherited
-   * context from a parent conversation).  `countPersistedMessages` subtracts
-   * this so `compactedPersistedMessages` only reflects DB-backed messages.
-   * Set by `Conversation.injectInheritedContext` and consumed (decremented)
-   * after a successful compaction pass.
+   * context from a parent conversation). The compactor subtracts this from
+   * `compactedMessages` so `compactedPersistedMessages` only reflects DB
+   * rows. Decremented after a successful compaction.
    */
   nonPersistedPrefixCount = 0;
-  /**
-   * True when the message at index 0 is a context summary that was inherited
-   * from a parent fork (i.e. injected as part of the non-persisted prefix),
-   * rather than produced by this conversation's own compaction. The parent
-   * summary sits at index 0 but is excluded from `compactableMessages` by
-   * `summaryOffset`, so its slot in `nonPersistedPrefixCount` must be
-   * accounted for separately. Cleared after the first compaction replaces
-   * the parent summary with a child-owned one.
-   */
   summaryIsInjected = false;
-  /**
-   * Cached resolved system prompt. Lazily populated on first access via the
-   * `systemPrompt` getter and cleared after each compaction pass so the next
-   * pass picks up any prompt changes.
-   */
   private _resolvedSystemPrompt: string | undefined;
 
   constructor(options: ContextWindowManagerOptions) {
@@ -359,27 +185,21 @@ export class ContextWindowManager {
     this._systemPrompt = options.systemPrompt;
     this.config = options.config;
     this.toolTokenBudget = options.toolTokenBudget ?? 0;
+    this.conversationId = options.conversationId;
+    this.resolveTools = options.resolveTools;
   }
 
   updateConfig(config: ContextWindowConfig): void {
     this.config = config;
   }
 
-  /**
-   * Provider key for the local token estimator. Wrapper providers (e.g.
-   * OpenRouter routing to `anthropic/*`) override `tokenEstimationProvider`
-   * so image/PDF sizing uses the same rules as the upstream API instead of
-   * the generic `base64/4` fallback.
-   */
   private get estimationProviderName(): string {
     return this.provider.tokenEstimationProvider ?? this.provider.name;
   }
 
-  /** Lazily resolve and cache the system prompt for the duration of a compaction pass. */
   private get systemPrompt(): string {
-    if (this._resolvedSystemPrompt !== undefined) {
+    if (this._resolvedSystemPrompt !== undefined)
       return this._resolvedSystemPrompt;
-    }
     const resolved =
       typeof this._systemPrompt === "function"
         ? this._systemPrompt()
@@ -392,21 +212,26 @@ export class ContextWindowManager {
     this._resolvedSystemPrompt = undefined;
   }
 
+  private resolveCompactionConfig(): CompactionConfig {
+    return getConfig().compaction;
+  }
+
   /**
-   * Cheap pre-check: returns whether the estimated token count exceeds
-   * the compaction threshold, along with the estimated token count so
-   * callers can pass it into `maybeCompact()` via `precomputedEstimate`
-   * to avoid a redundant tokenization pass.
+   * Cheap pre-check — estimate the current token count and compare against
+   * `compaction.autoThreshold`. Callers pass the estimate back through
+   * `precomputedEstimate` on the {@link maybeCompact} call to avoid
+   * re-tokenizing the same history twice.
    */
   shouldCompact(messages: Message[]): ShouldCompactResult {
-    if (!this.config.enabled) return { needed: false, estimatedTokens: 0 };
+    const compaction = this.resolveCompactionConfig();
+    if (!compaction.enabled) return { needed: false, estimatedTokens: 0 };
     try {
       const estimated = estimatePromptTokens(messages, this.systemPrompt, {
         providerName: this.estimationProviderName,
         toolTokenBudget: this.toolTokenBudget,
       });
       const threshold = Math.floor(
-        this.config.maxInputTokens * this.config.compactThreshold,
+        this.config.maxInputTokens * compaction.autoThreshold,
       );
       return { needed: estimated >= threshold, estimatedTokens: estimated };
     } finally {
@@ -431,6 +256,7 @@ export class ContextWindowManager {
     signal?: AbortSignal,
     options?: ContextWindowCompactOptions,
   ): Promise<ContextWindowResult> {
+    const compaction = this.resolveCompactionConfig();
     const previousEstimatedInputTokens =
       options?.precomputedEstimate ??
       estimatePromptTokens(messages, this.systemPrompt, {
@@ -438,1264 +264,115 @@ export class ContextWindowManager {
         toolTokenBudget: this.toolTokenBudget,
       });
     const thresholdTokens = Math.floor(
-      this.config.maxInputTokens * this.config.compactThreshold,
+      this.config.maxInputTokens * compaction.autoThreshold,
     );
-    const existingSummary = getSummaryFromContextMessage(messages[0]);
 
-    if (!this.config.enabled) {
-      return {
-        messages,
-        compacted: false,
-        previousEstimatedInputTokens,
-        estimatedInputTokens: previousEstimatedInputTokens,
+    if (!compaction.enabled) {
+      return noopResult(messages, previousEstimatedInputTokens, {
         maxInputTokens: this.config.maxInputTokens,
         thresholdTokens,
-        compactedMessages: 0,
-        compactedPersistedMessages: 0,
-        summaryCalls: 0,
-        summaryInputTokens: 0,
-        summaryOutputTokens: 0,
-        summaryModel: "",
-        summaryText: existingSummary ?? "",
-        reason: "context window compaction disabled",
-      };
+        reason: "compaction disabled",
+      });
     }
 
-    if (!options?.force && previousEstimatedInputTokens < thresholdTokens) {
-      return {
-        messages,
-        compacted: false,
-        previousEstimatedInputTokens,
-        estimatedInputTokens: previousEstimatedInputTokens,
+    if (this.conversationId == null) {
+      // The compactor needs the conversation id to look up image
+      // attachments and DB timestamps. If we don't have one (legacy test
+      // path, ad-hoc instantiation), skip — never fabricate one.
+      log.warn(
+        "ContextWindowManager has no conversationId — skipping compaction",
+      );
+      return noopResult(messages, previousEstimatedInputTokens, {
         maxInputTokens: this.config.maxInputTokens,
         thresholdTokens,
-        compactedMessages: 0,
-        compactedPersistedMessages: 0,
-        summaryCalls: 0,
-        summaryInputTokens: 0,
-        summaryOutputTokens: 0,
-        summaryModel: "",
-        summaryText: existingSummary ?? "",
-        reason: "below compaction threshold",
-      };
+        reason: "no conversation id",
+      });
     }
 
-    const summaryOffset = existingSummary != null ? 1 : 0;
-    const userTurnStarts = collectUserTurnStartIndexes(messages);
-    if (userTurnStarts.length === 0) {
-      return {
-        messages,
-        compacted: false,
-        previousEstimatedInputTokens,
-        estimatedInputTokens: previousEstimatedInputTokens,
+    if (!options?.force && previousEstimatedInputTokens < thresholdTokens) {
+      return noopResult(messages, previousEstimatedInputTokens, {
         maxInputTokens: this.config.maxInputTokens,
         thresholdTokens,
-        compactedMessages: 0,
-        compactedPersistedMessages: 0,
-        summaryCalls: 0,
-        summaryInputTokens: 0,
-        summaryOutputTokens: 0,
-        summaryModel: "",
-        summaryText: existingSummary ?? "",
-        reason: "no user turns available for compaction",
-      };
+        reason: "below auto threshold",
+      });
     }
 
-    const keepPlanInitial = this.pickKeepBoundary(messages, userTurnStarts, {
-      minKeepRecentUserTurns: options?.minKeepRecentUserTurns,
-      targetInputTokensOverride: options?.targetInputTokensOverride,
-      conversationOriginChannel: options?.conversationOriginChannel,
-      force: options?.force,
+    const args: CompactionRunArgs = {
+      conversationId: this.conversationId,
+      messages,
+      provider: this.provider,
+      systemPrompt: this.systemPrompt,
+      tools: this.resolveTools?.(),
+      compaction,
+      maxInputTokens: this.config.maxInputTokens,
       previousEstimatedInputTokens,
-    });
-    // Under force (user-explicit `/compact`), never route through the
-    // "already fits" / "truncated tool results without summarization"
-    // early-return — those are no-op responses to a direct user command.
-    // The boundary can collapse to the summary in two cases the
-    // projection-optimism clamp in pickKeepBoundary does not cover:
-    //   1. `adjustForToolPairs` walked the boundary back through a
-    //      tool_use/tool_result chain at the start of the conversation.
-    //   2. The binary search settled below `userTurnStarts.length` (so
-    //      the clamp at the top of pickKeepBoundary did not fire) but
-    //      `adjustForToolPairs` still walked the resulting boundary
-    //      backwards past `summaryOffset`.
-    // Rescue: restore the binary search's intended keep depth (capped at
-    // `length - 1` so we always summarize at least one turn) and bypass
-    // `adjustForToolPairs`. The kept region's first message may then
-    // contain a `tool_result` whose matching `tool_use` lives in the
-    // compacted region; we strip such orphans below before assembling
-    // the final messages array so the next agent turn does not fail
-    // when sending to the LLM.
-    const forceRescueApplied =
-      options?.force === true &&
-      keepPlanInitial.keepFromIndex <= summaryOffset &&
-      userTurnStarts.length >= 2;
-    const safeKeepTurns = Math.max(
-      1,
-      Math.min(keepPlanInitial.keepTurns, userTurnStarts.length - 1),
-    );
-    const keepPlan = forceRescueApplied
-      ? {
-          keepFromIndex: userTurnStarts[userTurnStarts.length - safeKeepTurns],
-          keepTurns: safeKeepTurns,
-        }
-      : keepPlanInitial;
-    if (keepPlan.keepFromIndex <= summaryOffset) {
-      // All turns fit after truncation projection, but the real in-memory
-      // messages may still contain un-truncated tool results. Apply truncation
-      // so the caller gets the token savings even without summarization.
-      const { messages: truncatedMessages, truncatedCount } =
-        truncateToolResultsAcrossHistory(
-          messages,
-          COMPACTION_TOOL_RESULT_MAX_CHARS,
-        );
-      const didTruncate = truncatedCount > 0;
-      const estimatedAfterTruncation = didTruncate
-        ? estimatePromptTokens(truncatedMessages, this.systemPrompt, {
-            providerName: this.estimationProviderName,
-            toolTokenBudget: this.toolTokenBudget,
-          })
-        : previousEstimatedInputTokens;
-      // Under force with only one user turn, the rescue above could not
-      // fire — there is nothing earlier to summarize. Surface that
-      // explicitly instead of "conversation already fits..." so the user
-      // knows why `/compact` did not produce a summary.
-      const noSummarizationReason =
-        options?.force && userTurnStarts.length < 2
-          ? "only one user turn — nothing earlier to compact"
-          : "conversation already fits within the compaction target";
-      return {
-        messages: truncatedMessages,
-        compacted: didTruncate,
-        previousEstimatedInputTokens,
-        estimatedInputTokens: estimatedAfterTruncation,
-        maxInputTokens: this.config.maxInputTokens,
-        thresholdTokens,
-        compactedMessages: 0,
-        compactedPersistedMessages: 0,
-        summaryCalls: 0,
-        summaryInputTokens: 0,
-        summaryOutputTokens: 0,
-        summaryModel: "",
-        summaryText: existingSummary ?? "",
-        reason: didTruncate
-          ? "truncated tool results without summarization"
-          : noSummarizationReason,
-      };
-    }
-
-    const compactableMessages = messages.slice(
-      summaryOffset,
-      keepPlan.keepFromIndex,
-    );
-    if (compactableMessages.length === 0) {
-      return {
-        messages,
-        compacted: false,
-        previousEstimatedInputTokens,
-        estimatedInputTokens: previousEstimatedInputTokens,
-        maxInputTokens: this.config.maxInputTokens,
-        thresholdTokens,
-        compactedMessages: 0,
-        compactedPersistedMessages: 0,
-        summaryCalls: 0,
-        summaryInputTokens: 0,
-        summaryOutputTokens: 0,
-        summaryModel: "",
-        summaryText: existingSummary ?? "",
-        reason: "no eligible messages to compact",
-      };
-    }
+      force: options?.force,
+      signal,
+      overrideProfile: options?.overrideProfile ?? null,
+      nonPersistedPrefixCount: this.nonPersistedPrefixCount,
+    };
 
-    // When the summary at index 0 was injected from a parent fork, it
-    // contributes 1 to `nonPersistedPrefixCount` but is excluded from
-    // `compactableMessages` by `summaryOffset`; subtract it here so the
-    // remaining injected count lines up with compactableMessages. A summary
-    // produced by this conversation's own prior compaction is not part of
-    // `nonPersistedPrefixCount` (already decremented), so no subtraction.
-    const injectedSummaryOffset = this.summaryIsInjected ? summaryOffset : 0;
-    const injectedInCompactable = Math.min(
-      Math.max(0, this.nonPersistedPrefixCount - injectedSummaryOffset),
-      compactableMessages.length,
-    );
-    const compactedPersistedMessages =
-      countPersistedMessages(compactableMessages) - injectedInCompactable;
-    const rawProjectedMessages = [
-      createContextSummaryMessage(existingSummary ?? "Projected summary"),
-      ...messages.slice(keepPlan.keepFromIndex),
-    ];
-    const { messages: projectedMessages } = truncateToolResultsAcrossHistory(
-      rawProjectedMessages,
-      COMPACTION_TOOL_RESULT_MAX_CHARS,
-    );
-    const projectedInputTokens = estimatePromptTokens(
-      projectedMessages,
-      this.systemPrompt,
-      {
-        providerName: this.estimationProviderName,
-        toolTokenBudget: this.toolTokenBudget,
-      },
-    );
-    const projectedGainTokens = Math.max(
-      0,
-      previousEstimatedInputTokens - projectedInputTokens,
-    );
-    const severePressure =
-      previousEstimatedInputTokens >=
-      Math.floor(this.config.maxInputTokens * SEVERE_PRESSURE_RATIO);
-    const lastCompactedAt = options?.lastCompactedAt;
+    const result = await runAssistantDrivenCompaction(args);
 
-    // Adaptive cooldown: conversations growing quickly (high projected gain) compact
-    // sooner. Scale the cooldown inversely with the growth-rate multiplier, capped at
-    // 1/4 of the base cooldown so we never check more than 4× as frequently.
-    const growthRateMultiplier = Math.max(
-      1,
-      projectedGainTokens / MIN_GAIN_TOKENS_DURING_COOLDOWN,
-    );
-    const adaptiveCooldownMs = Math.max(
-      COMPACTION_COOLDOWN_MS / 4,
-      COMPACTION_COOLDOWN_MS / growthRateMultiplier,
-    );
-    const withinCooldown =
-      typeof lastCompactedAt === "number" &&
-      Date.now() - lastCompactedAt < adaptiveCooldownMs;
+    if (!result.compacted) return result;
 
-    // The adaptive cooldown is already tuned to be shorter for fast-growing
-    // conversations (high projectedGainTokens → smaller adaptiveCooldownMs).
-    // Removing the redundant MIN_GAIN_TOKENS_DURING_COOLDOWN guard here lets
-    // that shorter cooldown actually gate compaction: high-growth conversations
-    // break out of the cooldown sooner and compact more frequently.
-    // force=true bypasses the cooldown so context-too-large recovery can always
-    // attempt a compaction even within the cooldown window.
-    if (withinCooldown && !severePressure && !options?.force) {
-      log.debug(
+    // Recompute the post-compaction token estimate now that the message
+    // array has been rebuilt. The compactor returns a conservative
+    // placeholder; the agent loop wants the real number for its next
+    // budget decision.
+    let estimatedInputTokens = result.estimatedInputTokens;
+    try {
+      estimatedInputTokens = estimatePromptTokens(
+        result.messages,
+        this.systemPrompt,
         {
-          projectedGainTokens,
-          adaptiveCooldownMs,
-          growthRateMultiplier,
-          msSinceCompaction:
-            typeof lastCompactedAt === "number"
-              ? Date.now() - lastCompactedAt
-              : null,
+          providerName: this.estimationProviderName,
+          toolTokenBudget: this.toolTokenBudget,
         },
-        "Compaction cooldown active",
       );
-      return {
-        messages,
-        compacted: false,
-        previousEstimatedInputTokens,
-        estimatedInputTokens: previousEstimatedInputTokens,
-        maxInputTokens: this.config.maxInputTokens,
-        thresholdTokens,
-        compactedMessages: 0,
-        compactedPersistedMessages: 0,
-        summaryCalls: 0,
-        summaryInputTokens: 0,
-        summaryOutputTokens: 0,
-        summaryModel: "",
-        summaryText: existingSummary ?? "",
-        reason: "compaction cooldown active",
-      };
-    }
-
-    // `severePressure` already bypasses this guard to keep context from
-    // overflowing. Forced compaction also bypasses: when the user
-    // explicitly types `/compact` we must summarize whatever is
-    // available rather than return "insufficient compactable persisted
-    // messages" — that is a no-op response to a direct user command.
-    if (
-      compactedPersistedMessages < MIN_COMPACTABLE_PERSISTED_MESSAGES &&
-      !severePressure &&
-      !options?.force
-    ) {
-      return {
-        messages,
-        compacted: false,
-        previousEstimatedInputTokens,
-        estimatedInputTokens: previousEstimatedInputTokens,
-        maxInputTokens: this.config.maxInputTokens,
-        thresholdTokens,
-        compactedMessages: 0,
-        compactedPersistedMessages: 0,
-        summaryCalls: 0,
-        summaryInputTokens: 0,
-        summaryOutputTokens: 0,
-        summaryModel: "",
-        summaryText: existingSummary ?? "",
-        reason: "insufficient compactable persisted messages",
-      };
-    }
-
-    const retainedThreadRefs = collectRetainedThreadReferences(
-      messages.slice(keepPlan.keepFromIndex),
-    );
-    // Strip runtime injections (memory, turn context, workspace hints, etc.)
-    // from the messages fed to the summarizer. These blocks are system
-    // metadata; leaving them in causes the summary to echo rotating memory
-    // content instead of the actual conversation. The caller's live message
-    // array is untouched so prefix caching stays intact.
-    const transcriptSource = stripCompactionOnlyInjections(compactableMessages);
-    const transcriptBlocks = this.capTranscriptBlocksToTokenBudget(
-      serializeMessagesToContentBlocks(transcriptSource),
-      existingSummary ?? "No previous summary.",
-      retainedThreadRefs,
-    );
-    const summaryUpdate = await this.updateSummary(
-      existingSummary ?? "No previous summary.",
-      transcriptBlocks,
-      retainedThreadRefs,
-      signal,
-      options?.overrideProfile ?? null,
-    );
-    const summaryInputTokens = summaryUpdate.inputTokens;
-    const summaryOutputTokens = summaryUpdate.outputTokens;
-    const summaryModel = summaryUpdate.model;
-    const summaryCacheCreationInputTokens =
-      summaryUpdate.cacheCreationInputTokens;
-    const summaryCacheReadInputTokens = summaryUpdate.cacheReadInputTokens;
-    const summaryFailed = summaryUpdate.failed;
-    const summaryRawResponses: unknown[] = [];
-    if (Array.isArray(summaryUpdate.rawResponse)) {
-      summaryRawResponses.push(...summaryUpdate.rawResponse);
-    } else if (summaryUpdate.rawResponse !== undefined) {
-      summaryRawResponses.push(summaryUpdate.rawResponse);
+    } catch (err) {
+      log.warn({ err }, "Post-compaction token estimate failed");
     }
-    const summaryCalls = 1;
-
-    // Force-keep the most recent assistant text from the compactable region
-    // by splicing it verbatim into the summary message. This is independent
-    // of what the LLM summarizer chose to surface — when compaction
-    // interrupts a long assistant work span, this anchor preserves the
-    // model's last self-narration ("Next step: …", "About to …") so the
-    // post-compaction model has unambiguous continuity instead of falling
-    // back to a "where am I?" recovery shape.
-    const tailAnchorText = extractTailAssistantText(compactableMessages);
-    const summary =
-      tailAnchorText != null
-        ? appendTailAnchorToSummary(summaryUpdate.summary, tailAnchorText)
-        : summaryUpdate.summary;
-
-    // Media (images, files) in kept turns is preserved naturally — those
-    // turns are carried forward as-is and their token cost is already
-    // accounted for by pickKeepBoundary's estimatePromptTokens call.
-    // Images in compacted turns are passed to the summarizer so it can
-    // describe their visual content in the summary text.
-    const summaryMessage = createContextSummaryMessage(summary);
 
-    const { messages: truncatedKeptMessages } =
-      truncateToolResultsAcrossHistory(
-        messages.slice(keepPlan.keepFromIndex),
-        COMPACTION_TOOL_RESULT_MAX_CHARS,
-      );
-    // The force-rescue boundary bypasses `adjustForToolPairs`, so the
-    // kept region may contain `tool_result` blocks whose matching
-    // `tool_use` is in the (now-compacted) prefix. Strip those orphans
-    // so the next agent turn does not fail with an LLM API error.
-    const keptMessages = forceRescueApplied
-      ? stripOrphanToolResults(truncatedKeptMessages)
-      : truncatedKeptMessages;
-    const compactedMessages = [summaryMessage, ...keptMessages];
-    const estimatedInputTokens = estimatePromptTokens(
-      compactedMessages,
-      this.systemPrompt,
-      {
-        providerName: this.estimationProviderName,
-        toolTokenBudget: this.toolTokenBudget,
-      },
+    // Consume any non-persisted prefix messages that were compacted away
+    // and clear the injected-summary flag.
+    const compactedAway = Math.min(
+      this.nonPersistedPrefixCount,
+      result.compactedMessages,
     );
-    // Consume the injected prefix messages that were compacted away. When the
-    // parent-injected summary was replaced by a freshly produced child summary,
-    // also consume its slot (it was excluded from injectedInCompactable via
-    // injectedSummaryOffset) and clear the flag so subsequent compactions treat
-    // the summary at index 0 as child-owned.
     this.nonPersistedPrefixCount = Math.max(
       0,
-      this.nonPersistedPrefixCount -
-        injectedInCompactable -
-        injectedSummaryOffset,
+      this.nonPersistedPrefixCount - compactedAway,
     );
     this.summaryIsInjected = false;
 
-    log.info(
-      {
-        previousEstimatedInputTokens,
-        estimatedInputTokens,
-        compactedMessages: compactableMessages.length,
-        compactedPersistedMessages,
-        keepTurns: keepPlan.keepTurns,
-        summaryCalls,
-      },
-      "Compacted conversation context window",
-    );
-
-    return {
-      messages: compactedMessages,
-      compacted: true,
-      previousEstimatedInputTokens,
-      estimatedInputTokens,
-      maxInputTokens: this.config.maxInputTokens,
-      thresholdTokens,
-      compactedMessages: compactableMessages.length,
-      compactedPersistedMessages,
-      summaryCalls,
-      summaryInputTokens,
-      summaryOutputTokens,
-      summaryModel,
-      summaryCallSite: CONVERSATION_SUMMARY_CALL_SITE,
-      summaryOverrideProfile: options?.overrideProfile ?? null,
-      summaryCacheCreationInputTokens,
-      summaryCacheReadInputTokens,
-      summaryRawResponses,
-      summaryText: summary,
-      summaryFailed,
-    };
-  }
-
-  private get targetInputTokens(): number {
-    return Math.floor(
-      this.config.maxInputTokens *
-        (this.config.targetBudgetRatio - this.config.summaryBudgetRatio),
-    );
+    return { ...result, estimatedInputTokens };
   }
-
-  private pickKeepBoundary(
-    messages: Message[],
-    userTurnStarts: number[],
-    opts?: {
-      minKeepRecentUserTurns?: number;
-      targetInputTokensOverride?: number;
-      conversationOriginChannel?: string;
-      force?: boolean;
-      previousEstimatedInputTokens?: number;
-    },
-  ): { keepFromIndex: number; keepTurns: number } {
-    // Slack-originated conversations rely on multi-turn thread context
-    // (reply chains, quoted messages, contextual references). Bump the
-    // default keep floor for them so compaction does not summarize away
-    // recent turns that the next reply may directly cite. Explicit
-    // `minKeepRecentUserTurns` (including emergency `0`) wins.
-    const defaultTurns = opts?.conversationOriginChannel === "slack" ? 8 : 1;
-    const minFloor = Math.min(
-      Math.max(0, Math.floor(opts?.minKeepRecentUserTurns ?? defaultTurns)),
-      userTurnStarts.length,
-    );
-    const targetTokens = Math.min(
-      opts?.targetInputTokensOverride ?? this.targetInputTokens,
-      this.targetInputTokens,
-    );
-
-    // Binary search for the maximum keepTurns whose projected tokens fit
-    // within the budget. Token count is monotonically non-decreasing with
-    // keepTurns (more turns = more tokens), so binary search is valid.
-    const projectedTokensForKeep = (turns: number): number => {
-      const fromIndex =
-        turns === 0
-          ? messages.length
-          : (userTurnStarts[userTurnStarts.length - turns] ?? messages.length);
-      const rawProjected = [
-        createContextSummaryMessage("Projected summary"),
-        ...messages.slice(fromIndex),
-      ];
-      const { messages: projectedMessages } = truncateToolResultsAcrossHistory(
-        rawProjected,
-        COMPACTION_TOOL_RESULT_MAX_CHARS,
-      );
-      return estimatePromptTokens(projectedMessages, this.systemPrompt, {
-        providerName: this.estimationProviderName,
-        toolTokenBudget: this.toolTokenBudget,
-      });
-    };
-
-    let lo = minFloor;
-    let hi = userTurnStarts.length;
-
-    // Fast path: if keeping all turns already fits, skip the search.
-    if (hi > lo && projectedTokensForKeep(hi) > targetTokens) {
-      // Binary search: find the largest keepTurns where projected tokens fit.
-      while (lo < hi) {
-        const mid = lo + Math.ceil((hi - lo) / 2);
-        if (projectedTokensForKeep(mid) <= targetTokens) {
-          lo = mid;
-        } else {
-          hi = mid - 1;
-        }
-      }
-    } else {
-      lo = hi;
-    }
-
-    // Under forced compaction with only the implicit default floor in play,
-    // that floor stops being an absolute override when the kept region still
-    // exceeds the target. Walk keepTurns below the floor — down to 0 if
-    // needed — so /compact can always drive the conversation toward target,
-    // even when the floor turn itself is oversized (e.g. a huge paste in the
-    // last user message). Exceptions that still treat the floor as hard:
-    //   - Explicit `minKeepRecentUserTurns` (the caller opted in to that
-    //     floor; emergency recovery already passes 0 when it wants to go all
-    //     the way down).
-    //   - Slack origin (the bumped 8-turn floor protects thread reply chains
-    //     and quoted-message context that the next reply may directly cite).
-    // Automatic mid-loop compaction (force !== true) always honors the floor
-    // so the in-flight agent turn isn't summarized away.
-    const floorIsImplicitDefault =
-      opts?.minKeepRecentUserTurns === undefined &&
-      opts?.conversationOriginChannel !== "slack";
-    if (
-      opts?.force &&
-      floorIsImplicitDefault &&
-      projectedTokensForKeep(lo) > targetTokens
-    ) {
-      while (lo > 0 && projectedTokensForKeep(lo) > targetTokens) {
-        lo--;
-      }
-    }
-
-    // The projection's summary-swap and tool_result truncation can make
-    // projectedTokensForKeep(hi) optimistically fit even when the live
-    // conversation is well over target — sending /compact through the
-    // "already fits" skip path as a no-op. Clamp lo so summarization runs.
-    if (
-      opts?.force &&
-      floorIsImplicitDefault &&
-      lo === userTurnStarts.length &&
-      lo > 0 &&
-      (opts?.previousEstimatedInputTokens ?? 0) > targetTokens
-    ) {
-      lo -= 1;
-    }
-
-    const keepTurns = lo;
-    const rawKeepFromIndex =
-      keepTurns === 0
-        ? messages.length
-        : (userTurnStarts[userTurnStarts.length - keepTurns] ??
-          messages.length);
-    const keepFromIndex = adjustForToolPairs(messages, rawKeepFromIndex);
-    return { keepFromIndex, keepTurns };
-  }
-
-  private get summaryMaxTokens(): number {
-    return Math.max(
-      1,
-      Math.floor(this.config.maxInputTokens * this.config.summaryBudgetRatio),
-    );
-  }
-
-  /**
-   * Trim the serialized transcript content blocks so that the summary prompt
-   * (system prompt + existing summary + transcript + scaffolding) fits within
-   * the provider's input token limit, minus the output budget reserved for the
-   * summary itself.
-   *
-   * When the transcript exceeds the budget, blocks are dropped from the
-   * beginning (oldest messages first) to preserve recent context. Image blocks
-   * are dropped before text blocks within each pass since they are expensive
-   * and their surrounding text context already captures the conversation flow.
-   */
-  private capTranscriptBlocksToTokenBudget(
-    blocks: ContentBlock[],
-    currentSummary: string,
-    retainedThreadRefs: string[],
-  ): ContentBlock[] {
-    const retainedRefsText = retainedThreadRefs.join("\n");
-    const overheadTokens =
-      estimateTextTokens(SUMMARY_SYSTEM_PROMPT) +
-      estimateTextTokens(currentSummary) +
-      estimateTextTokens(retainedRefsText) +
-      // Scaffolding text in buildSummaryContentBlocks ("Update the summary...",
-      // section headers, etc.) — generous fixed estimate.
-      200 +
-      this.summaryMaxTokens;
-
-    const maxTranscriptTokens = Math.max(
-      0,
-      this.config.maxInputTokens - overheadTokens,
-    );
-
-    const estimateBlockTokens = (b: ContentBlock): number =>
-      estimateContentBlockTokens(b, {
-        providerName: this.estimationProviderName,
-      });
-
-    let totalTokens = 0;
-    for (const block of blocks) {
-      totalTokens += estimateBlockTokens(block);
-    }
-    const originalTotalTokens = totalTokens;
-    if (totalTokens <= maxTranscriptTokens) return blocks;
-
-    // First pass: drop images from the beginning until we fit or run out of
-    // images to drop. Images are high-cost and their text context (message
-    // headers, surrounding tool_use/tool_result serializations) is preserved.
-    const result = [...blocks];
-    for (
-      let i = 0;
-      i < result.length && totalTokens > maxTranscriptTokens;
-      i++
-    ) {
-      if (result[i].type === "image") {
-        totalTokens -= estimateBlockTokens(result[i]);
-        const stub: ContentBlock = {
-          type: "text",
-          text: `[image omitted from summary context]`,
-        };
-        totalTokens += estimateBlockTokens(stub);
-        result[i] = stub;
-      }
-    }
-    if (totalTokens <= maxTranscriptTokens) return result;
-
-    // Second pass: drop text blocks from the beginning (oldest) until we fit.
-    // If a single text block exceeds the remaining budget, truncate it rather
-    // than dropping it entirely so the summarizer always has content to work with.
-    let dropUntil = 0;
-    let droppedTokens = 0;
-    for (
-      let i = 0;
-      i < result.length && totalTokens > maxTranscriptTokens;
-      i++
-    ) {
-      const blockTokens = estimateBlockTokens(result[i]);
-      const excess = totalTokens - maxTranscriptTokens;
-      if (blockTokens > excess && result[i].type === "text") {
-        // Truncate this block to shed exactly the excess tokens.
-        // Subtract the cost of the "[...truncated] " prefix so the final
-        // block (prefix + kept text) stays within budget.
-        const truncationPrefix = "[...truncated] ";
-        const prefixTokens = estimateTextTokens(truncationPrefix);
-        const keepTokens = Math.max(1, blockTokens - excess - prefixTokens);
-        const text = (result[i] as { type: "text"; text: string }).text;
-        // Approximate: 1 token ≈ 4 characters for truncation purposes.
-        const keepChars = Math.max(1, Math.floor(keepTokens * 4));
-        const truncatedText = text.slice(-keepChars);
-        const truncatedBlock: ContentBlock = {
-          type: "text",
-          text: `${truncationPrefix}${truncatedText}`,
-        };
-        const newBlockTokens = estimateBlockTokens(truncatedBlock);
-        droppedTokens += blockTokens - newBlockTokens;
-        totalTokens -= blockTokens - newBlockTokens;
-        result[i] = truncatedBlock;
-        dropUntil = i;
-        break;
-      }
-      droppedTokens += blockTokens;
-      totalTokens -= blockTokens;
-      dropUntil = i + 1;
-    }
-
-    log.info(
-      {
-        originalTokens: originalTotalTokens,
-        cappedTokens: maxTranscriptTokens,
-        droppedTokens,
-      },
-      "Capped summary transcript blocks to fit provider input limit",
-    );
-
-    return [
-      { type: "text", text: "[earlier messages truncated]" } as ContentBlock,
-      ...result.slice(dropUntil),
-    ];
-  }
-
-  private async updateSummary(
-    currentSummary: string,
-    transcriptBlocks: ContentBlock[],
-    retainedThreadRefs: string[],
-    signal?: AbortSignal,
-    overrideProfile?: string | null,
-  ): Promise<{
-    summary: string;
-    inputTokens: number;
-    outputTokens: number;
-    model: string;
-    cacheCreationInputTokens: number;
-    cacheReadInputTokens: number;
-    rawResponse?: unknown;
-    /**
-     * True when the provider.sendMessage call threw and the local fallback
-     * was used. Callers (the agent loop) use this to drive circuit-breaker
-     * state without having to reimplement the fallback themselves.
-     */
-    failed: boolean;
-  }> {
-    // When the existing summary is already consuming most of its budget,
-    // nudge the model to compress older durable content aggressively so
-    // incremental-update passes don't let the summary grow unboundedly.
-    const existingSummaryTokens = estimateTextTokens(currentSummary);
-    const compressionPressure =
-      existingSummaryTokens >=
-      this.summaryMaxTokens * SUMMARY_COMPRESSION_PRESSURE_RATIO;
-    const contentBlocks = buildSummaryContentBlocks(
-      currentSummary,
-      transcriptBlocks,
-      retainedThreadRefs,
-      { compressionPressure },
-    );
-    const summaryMessage: Message = { role: "user", content: contentBlocks };
-    let failed = false;
-    try {
-      const providerConfig: Record<string, unknown> = {
-        callSite: CONVERSATION_SUMMARY_CALL_SITE,
-        usageTracking: "manual",
-        max_tokens: this.summaryMaxTokens,
-      };
-      if (overrideProfile) {
-        providerConfig.overrideProfile = overrideProfile;
-      }
-      const response = await this.provider.sendMessage(
-        [summaryMessage],
-        undefined,
-        SUMMARY_SYSTEM_PROMPT,
-        {
-          config: providerConfig,
-          signal,
-        },
-      );
-
-      const nextSummary = extractText(response.content).trim();
-      if (nextSummary.length > 0) {
-        return {
-          summary: this.clampSummary(nextSummary),
-          inputTokens: response.usage.inputTokens,
-          outputTokens: response.usage.outputTokens,
-          model: response.model,
-          cacheCreationInputTokens:
-            response.usage.cacheCreationInputTokens ?? 0,
-          cacheReadInputTokens: response.usage.cacheReadInputTokens ?? 0,
-          rawResponse: response.rawResponse,
-          failed: false,
-        };
-      }
-    } catch (err) {
-      failed = true;
-      log.warn({ err }, "Summary generation failed, using local fallback");
-    }
-
-    // Fallback: extract text-only transcript for local summary generation.
-    const textTranscript = transcriptBlocks
-      .filter(
-        (b): b is Extract<ContentBlock, { type: "text" }> => b.type === "text",
-      )
-      .map((b) => b.text)
-      .join("\n\n");
-
-    return {
-      summary: fallbackSummary(currentSummary, textTranscript),
-      inputTokens: 0,
-      outputTokens: 0,
-      model: "",
-      cacheCreationInputTokens: 0,
-      cacheReadInputTokens: 0,
-      failed,
-    };
-  }
-
-  private clampSummary(summary: string): string {
-    // Budget in tokens → approximate char limit (4 chars ≈ 1 token).
-    const maxChars = this.summaryMaxTokens * 4;
-    if (summary.length <= maxChars) return summary;
-    return clampSummaryAtSectionBoundary(summary, maxChars);
-  }
-}
-
-/**
- * Truncate a markdown summary that exceeds `maxChars`, preferring a
- * section boundary (`\n## `) so we never cut a heading mid-text. Falls
- * back to a hard character slice when no boundary exists in the safe
- * region (first half of the budget).
- */
-export function clampSummaryAtSectionBoundary(
-  summary: string,
-  maxChars: number,
-): string {
-  if (summary.length <= maxChars) return summary;
-  const ELLIPSIS = "...";
-  // Hard limit we must stay under, leaving room for the ellipsis suffix.
-  const cutoff = maxChars - ELLIPSIS.length;
-  if (cutoff <= 0) return ELLIPSIS;
-  const head = safeStringSlice(summary, 0, cutoff);
-  // Find the last `## ` heading at a line start. Require it to be past the
-  // midpoint of the allowed region so we don't drop most of the summary
-  // just to hit a boundary — better to cut mid-section late than to keep
-  // almost nothing.
-  const halfway = Math.floor(cutoff / 2);
-  const boundary = head.lastIndexOf("\n## ");
-  if (boundary >= halfway) {
-    return `${head.slice(0, boundary).trimEnd()}\n${ELLIPSIS}`;
-  }
-  return `${head}${ELLIPSIS}`;
-}
-
-function collectUserTurnStartIndexes(messages: Message[]): number[] {
-  const starts: number[] = [];
-  for (let i = 0; i < messages.length; i++) {
-    const message = messages[i];
-    if (message.role !== "user") continue;
-    if (getSummaryFromContextMessage(message) != null) continue;
-    if (isToolResultOnly(message)) continue;
-    starts.push(i);
-  }
-  return starts;
-}
-
-/**
- * Count messages that have DB counterparts.  Context-summary messages are
- * in-memory-only and excluded; ALL other messages (including tool-result-only
- * user messages) have a corresponding row in the DB and must be counted so
- * that `contextCompactedMessageCount` indexes the DB array correctly.
- */
-function countPersistedMessages(messages: Message[]): number {
-  return messages.filter((message) => {
-    return getSummaryFromContextMessage(message) == null;
-  }).length;
-}
-
-function isSystemNoticeBlock(block: ContentBlock): boolean {
-  if (block.type !== "text") return false;
-  const text = (block as { text?: string }).text ?? "";
-  return (
-    text.startsWith("<system_notice>") && text.endsWith("</system_notice>")
-  );
 }
 
-/** A user message that contains ONLY tool_result blocks (no text or other content).
- *  System notice text blocks (retry nudges, progress checks) do not count as user content. */
-function isToolResultOnly(message: Message): boolean {
-  return (
-    message.content.length > 0 &&
-    message.content.every(
-      (block) =>
-        block.type === "tool_result" ||
-        block.type === "web_search_tool_result" ||
-        isSystemNoticeBlock(block),
-    )
-  );
-}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
 
-/**
- * Walk the keep boundary backward to ensure tool_use/tool_result pairs are
- * never split across the compaction boundary. If the first kept message is
- * a user message containing tool_result blocks whose matching tool_use blocks
- * live in the preceding (compacted-away) assistant message, include that
- * assistant message in the kept set.
- */
-function adjustForToolPairs(
+function noopResult(
   messages: Message[],
-  keepFromIndex: number,
-): number {
-  let idx = keepFromIndex;
-  while (idx > 0) {
-    const msg = messages[idx];
-    if (!msg || msg.role !== "user") break;
-
-    // Collect tool_use_ids referenced by tool_results in this user message
-    const referencedIds = new Set<string>();
-    for (const block of msg.content) {
-      if (
-        (block.type === "tool_result" ||
-          block.type === "web_search_tool_result") &&
-        "tool_use_id" in block
-      ) {
-        referencedIds.add((block as { tool_use_id: string }).tool_use_id);
-      }
-    }
-    if (referencedIds.size === 0) break;
-
-    // Check if the preceding assistant message contains matching tool_uses
-    const prev = messages[idx - 1];
-    if (!prev || prev.role !== "assistant") break;
-
-    const hasOrphanedPair = prev.content.some(
-      (block) =>
-        (block.type === "tool_use" || block.type === "server_tool_use") &&
-        "id" in block &&
-        referencedIds.has((block as { id: string }).id),
-    );
-    if (!hasOrphanedPair) break;
-
-    // Include the assistant message
-    idx--;
-
-    // The assistant message may itself be preceded by a tool_result user
-    // message that pairs with an even earlier assistant — continue the check
-    if (idx > 0 && messages[idx - 1]?.role === "user") {
-      idx--;
-    } else {
-      break;
-    }
-  }
-  return idx;
-}
-
-/**
- * Strip `tool_result` blocks whose matching `tool_use` is not present in
- * the message array. Used by the force-rescue path in `_maybeCompact`
- * which bypasses `adjustForToolPairs` to honor user-explicit `/compact`
- * commands — the kept region's first user message can otherwise contain
- * an orphan `tool_result`, which the LLM API rejects.
- *
- * A user message that contains only orphan `tool_result` blocks is
- * dropped entirely; partial messages keep the surviving content blocks.
- */
-function stripOrphanToolResults(messages: Message[]): Message[] {
-  const knownToolUseIds = new Set<string>();
-  for (const msg of messages) {
-    if (msg.role !== "assistant") continue;
-    for (const block of msg.content) {
-      if (
-        (block.type === "tool_use" || block.type === "server_tool_use") &&
-        "id" in block
-      ) {
-        knownToolUseIds.add((block as { id: string }).id);
-      }
-    }
-  }
-
-  return messages.flatMap((msg) => {
-    if (msg.role !== "user") return [msg];
-    let stripped = false;
-    const filtered = msg.content.filter((block) => {
-      if (
-        (block.type === "tool_result" ||
-          block.type === "web_search_tool_result") &&
-        "tool_use_id" in block
-      ) {
-        const id = (block as { tool_use_id: string }).tool_use_id;
-        if (!knownToolUseIds.has(id)) {
-          stripped = true;
-          return false;
-        }
-      }
-      return true;
-    });
-    if (!stripped) return [msg];
-    if (filtered.length === 0) return [];
-    return [{ ...msg, content: filtered }];
-  });
-}
-
-export function getSummaryFromContextMessage(
-  message: Message | undefined,
-): string | null {
-  if (!message) return null;
-  const text = extractText(message.content).trim();
-  if (!text.startsWith(CONTEXT_SUMMARY_MARKER)) return null;
-  if (INTERNAL_CONTEXT_SUMMARY_MESSAGES.has(message)) {
-    return stripContextSummaryTags(text);
-  }
-  return null;
-}
-
-function stripContextSummaryTags(text: string): string {
-  let inner = text.slice(CONTEXT_SUMMARY_MARKER.length);
-  const closeIdx = inner.lastIndexOf("</context_summary>");
-  if (closeIdx !== -1) {
-    inner = inner.slice(0, closeIdx);
-  }
-  return inner.trim();
-}
-
-export function createContextSummaryMessage(summary: string): Message {
-  const message: Message = {
-    role: "user",
-    content: [
-      {
-        type: "text",
-        text: `${CONTEXT_SUMMARY_MARKER}\n${summary}\n</context_summary>`,
-      },
-    ],
+  estimated: number,
+  opts: { maxInputTokens: number; thresholdTokens: number; reason: string },
+): ContextWindowResult {
+  return {
+    messages,
+    compacted: false,
+    previousEstimatedInputTokens: estimated,
+    estimatedInputTokens: estimated,
+    maxInputTokens: opts.maxInputTokens,
+    thresholdTokens: opts.thresholdTokens,
+    compactedMessages: 0,
+    compactedPersistedMessages: 0,
+    summaryCalls: 0,
+    summaryInputTokens: 0,
+    summaryOutputTokens: 0,
+    summaryModel: "",
+    summaryText: getSummaryFromContextMessage(messages[0]) ?? "",
+    reason: opts.reason,
   };
-  INTERNAL_CONTEXT_SUMMARY_MESSAGES.add(message);
-  return message;
-}
-
-/**
- * Walk `messages` backward and return the concatenated text content of the
- * most recent assistant message that contains at least one non-empty text
- * block. tool_use / tool_result / image / unknown blocks are skipped. The
- * result is trimmed and (if longer than `maxChars`) clamped from the START
- * so the END — where "next step" / "now I'll …" narration tends to land —
- * is preserved.
- *
- * Returns `null` when no eligible assistant text is found (e.g. compactable
- * region was all user/tool messages, or all assistant messages were
- * tool_use-only). The caller treats `null` as "no anchor to splice".
- *
- * Used by `_maybeCompact` to force-keep the last assistant text from the
- * compactable region into the post-compaction summary message, so the
- * model's most recent self-narration survives summarization regardless of
- * whether the LLM summarizer chose to surface it.
- */
-export function extractTailAssistantText(
-  messages: Message[],
-  maxChars: number = TAIL_ANCHOR_MAX_CHARS,
-): string | null {
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i];
-    if (message?.role !== "assistant") continue;
-    const text = extractText(message.content).trim();
-    if (text.length === 0) continue;
-    if (text.length <= maxChars) return text;
-    // Keep the END — most recent narration wins.
-    const truncated = safeStringSlice(
-      text,
-      text.length - maxChars,
-      text.length,
-    );
-    return `[...truncated] ${truncated}`;
-  }
-  return null;
-}
-
-/**
- * Splice a verbatim tail-anchor block onto the end of the LLM-produced
- * summary text. The tag-wrapped block is structurally distinct from any
- * `## ` section the LLM might generate, so it survives section-boundary
- * clamping in `clampSummaryAtSectionBoundary` (which only runs on the LLM
- * summary itself, before this splice).
- *
- * Idempotent: if the summary already ends with a `<verbatim_tail>…` block
- * (e.g. from a prior compaction whose summary was carried forward as
- * `existingSummary`), it is replaced rather than stacked, so successive
- * compactions don't accumulate stale tails.
- */
-export function appendTailAnchorToSummary(
-  summary: string,
-  tailText: string,
-): string {
-  const trimmed = summary.trimEnd();
-  const existingOpen = trimmed.lastIndexOf(TAIL_ANCHOR_OPEN_TAG);
-  const base =
-    existingOpen >= 0 ? trimmed.slice(0, existingOpen).trimEnd() : trimmed;
-  return `${base}\n\n${TAIL_ANCHOR_OPEN_TAG}\n${tailText.trim()}\n${TAIL_ANCHOR_CLOSE_TAG}`;
-}
-
-/**
- * Build content blocks for the summary prompt. Returns a mix of text blocks
- * (for the scaffolding, existing summary, and serialized non-image content)
- * and image blocks (preserved from the original messages so the summarizer
- * can describe what was in them).
- */
-function buildSummaryContentBlocks(
-  currentSummary: string,
-  transcriptBlocks: ContentBlock[],
-  retainedThreadRefs: string[],
-  options: { compressionPressure: boolean } = { compressionPressure: false },
-): ContentBlock[] {
-  const lines = [
-    "Update the summary with new transcript data.",
-    "If new information conflicts with older notes, keep the most recent and explicit detail.",
-    "Keep all unresolved asks and next steps.",
-    "For any images included below, describe their visual content in the summary so the information is preserved after compaction.",
-  ];
-  if (options.compressionPressure) {
-    lines.push(
-      "The existing summary is approaching its token budget. Compress older durable content aggressively (drop detail that is no longer load-bearing, merge bullets, tighten prose) while preserving the most recent turns' nuance.",
-    );
-  }
-  lines.push(
-    "",
-    "### Existing Summary",
-    currentSummary.trim().length > 0 ? currentSummary.trim() : "None.",
-    "",
-  );
-  if (retainedThreadRefs.length > 0) {
-    lines.push(
-      "### Retained Thread References",
-      "These reply tag lines remain in the live context after compaction. Each `→ Mxxxxxx` cites a parent message by alias; if that parent appears in the Transcript below, preserve its text verbatim.",
-      ...retainedThreadRefs.map((ref) => `- ${ref}`),
-      "",
-    );
-  }
-  lines.push("### Transcript");
-  return [
-    {
-      type: "text",
-      text: lines.join("\n"),
-    } as ContentBlock,
-    ...transcriptBlocks,
-  ];
-}
-
-/**
- * Scan retained-tail messages for Slack-style reply tag lines that cite a
- * thread parent via the `→ Mxxxxxx` alias convention. Returns the full tag
- * line for each match (de-duplicated, order-preserved) so the summarizer
- * has a concrete list of parents whose text must be preserved verbatim.
- *
- * Non-slack conversations and retained tails without any reply markers
- * produce an empty list — in that case the summarizer is told explicitly
- * that no verbatim preservation is required.
- */
-function collectRetainedThreadReferences(
-  retainedMessages: Message[],
-): string[] {
-  const seen = new Set<string>();
-  const out: string[] = [];
-  for (const msg of retainedMessages) {
-    for (const block of msg.content) {
-      if (block.type !== "text") continue;
-      const text = (block as { text: string }).text;
-      for (const line of text.split("\n")) {
-        if (!THREAD_REPLY_REFERENCE_PATTERN.test(line)) continue;
-        const trimmed = line.trim();
-        if (trimmed.length === 0) continue;
-        if (seen.has(trimmed)) continue;
-        seen.add(trimmed);
-        out.push(trimmed);
-      }
-    }
-  }
-  return out;
-}
-
-/**
- * Serialize messages into a sequence of content blocks. Text-based content
- * (tool calls, tool results, thinking, etc.) is serialized into text blocks.
- * Image blocks — both top-level and nested inside tool_result contentBlocks —
- * are preserved as-is so the summarizer LLM can see them.
- */
-function serializeMessagesToContentBlocks(messages: Message[]): ContentBlock[] {
-  const blocks: ContentBlock[] = [];
-  for (let i = 0; i < messages.length; i++) {
-    const msg = messages[i];
-    const textLines: string[] = [`Message #${i + 1} (${msg.role})`];
-
-    for (const block of msg.content) {
-      if (block.type === "image") {
-        // Flush accumulated text lines before the image.
-        if (textLines.length > 0) {
-          blocks.push({ type: "text", text: textLines.join("\n") });
-          textLines.length = 0;
-        }
-        blocks.push(block);
-      } else if (block.type === "tool_result") {
-        // guard:allow-tool-result-only — web_search_tool_result handled by serializeBlock via else branch
-        // Extract images from tool_result contentBlocks before serializing.
-        const collectedImages: ImageContent[] = [];
-        textLines.push(serializeToolResultBlock(block, collectedImages));
-        if (collectedImages.length > 0) {
-          // Flush text, emit collected images, then continue.
-          if (textLines.length > 0) {
-            blocks.push({ type: "text", text: textLines.join("\n") });
-            textLines.length = 0;
-          }
-          blocks.push(...collectedImages);
-        }
-      } else {
-        textLines.push(serializeBlock(block));
-      }
-    }
-
-    // Flush remaining text lines for this message.
-    if (textLines.length > 0) {
-      blocks.push({ type: "text", text: textLines.join("\n") });
-    }
-  }
-  return blocks;
-}
-
-/**
- * Serialize images nested inside tool_result contentBlocks, returning them
- * as separate content blocks to preserve for the summarizer.
- */
-function serializeToolResultBlock(
-  block: Extract<ContentBlock, { type: "tool_result" }>,
-  collectedImages: ImageContent[],
-): string {
-  if (block.contentBlocks) {
-    for (const cb of block.contentBlocks) {
-      if (cb.type === "image") {
-        collectedImages.push(cb);
-      }
-    }
-  }
-  return `tool_result ${block.tool_use_id}${
-    block.is_error ? " (error)" : ""
-  }: ${clampText(block.content)}`;
-}
-
-function serializeBlock(block: ContentBlock): string {
-  switch (block.type) {
-    case "text":
-      return `text: ${clampText(block.text)}`;
-    case "tool_use":
-      return `tool_use ${block.name}: ${clampText(stableJson(block.input))}`;
-    case "tool_result":
-      return `tool_result ${block.tool_use_id}${
-        block.is_error ? " (error)" : ""
-      }: ${clampText(block.content)}`;
-    case "image":
-      // Top-level images are handled by serializeMessagesToContentBlocks.
-      // This path is only hit for images in unexpected positions.
-      return `image: ${block.source.media_type}, ${
-        Math.ceil(block.source.data.length / 4) * 3
-      } bytes(base64)`;
-    case "file": {
-      const sizeBytes = Math.ceil(block.source.data.length / 4) * 3;
-      const parts = [
-        `file: ${block.source.filename}`,
-        block.source.media_type,
-        `${sizeBytes} bytes(base64)`,
-      ];
-      if (block.extracted_text) {
-        parts.push(`text=${clampText(block.extracted_text)}`);
-      }
-      return parts.join(", ");
-    }
-    case "thinking":
-      return `thinking: ${clampText(block.thinking)}`;
-    case "redacted_thinking":
-      return "redacted_thinking";
-    case "server_tool_use":
-      return `server_tool_use ${block.name}: ${clampText(stableJson(block.input))}`;
-    case "web_search_tool_result":
-      return `web_search_tool_result ${block.tool_use_id}`;
-    default:
-      return "unknown_block";
-  }
-}
-
-function clampText(text: string): string {
-  if (text.length <= MAX_BLOCK_PREVIEW_CHARS) return text;
-  return `${safeStringSlice(text, 0, MAX_BLOCK_PREVIEW_CHARS)}... [truncated ${
-    text.length - MAX_BLOCK_PREVIEW_CHARS
-  } chars]`;
-}
-
-function fallbackSummary(currentSummary: string, chunk: string): string {
-  const lines = chunk
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0);
-  const recentLines = lines.slice(-120).join("\n");
-  const merged = [
-    currentSummary.trim(),
-    "## Recent Progress",
-    recentLines.length > 0 ? recentLines : "No new details.",
-  ]
-    .filter((part) => part.length > 0)
-    .join("\n\n");
-  if (merged.length <= MAX_FALLBACK_SUMMARY_CHARS) return merged;
-  return merged.slice(merged.length - MAX_FALLBACK_SUMMARY_CHARS);
-}
-
-function extractText(content: ContentBlock[]): string {
-  return content
-    .filter(
-      (block): block is Extract<ContentBlock, { type: "text" }> =>
-        block.type === "text",
-    )
-    .map((block) => block.text)
-    .join("\n");
-}
-
-function stableJson(value: unknown): string {
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return "[unserializable]";
-  }
 }