@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/{daemon → plugins/defaults/compaction}/context-overflow-reducer.ts

@@ -9,39 +9,67 @@
  * messages is a no-op. Tiers are ordered so that less destructive
  * transformations are tried first.
  *
- * Tier progression:
- *   1. Forced compaction (emergency keep-boundary options)
+ * Rung progression:
+ *   0. Emergency summarize-around-last-tool-pair (preserves the most recent
+ *      tool call/result while aggressively compressing earlier history)
+ *   1. Forced full-history compaction (emergency keep-boundary options)
  *   2. Aggressive tool-result text truncation across retained history
  *   3. Media/file payload stubbing (replace images/files with text stubs)
  *   4. Runtime injection downgrade to minimal mode
+ *   terminal. Auto-compress the latest turn (policy-gated by the caller)
+ *
+ * Rungs 1–4 are the "middle tiers" and are bounded by `maxMiddleTierAttempts`.
+ * The emergency rung always runs first; the auto-compress rung runs last and
+ * only when the caller permits it. The caller invokes the reducer repeatedly,
+ * re-running the agent loop after each rung, until either the context fits or
+ * `state.exhausted` is true.
  */
 
-import type { ContextWindowConfig } from "../config/types.js";
+import type { ContextWindowConfig } from "../../../config/types.js";
 import {
   estimateContentBlockTokens,
   estimatePromptTokens,
-} from "../context/token-estimator.js";
-import { truncateToolResultsAcrossHistory } from "../context/tool-result-truncation.js";
-import type {
-  ContextWindowCompactOptions,
-  ContextWindowResult,
-} from "../context/window-manager.js";
-import type { Message } from "../providers/types.js";
+} from "../../../context/token-estimator.js";
+import { truncateToolResultsAcrossHistory } from "../../../context/tool-result-truncation.js";
 import {
   countMediaBlocks,
   estimateUnconditionalStubTokens,
   stripMediaPayloadsForRetry,
-} from "./conversation-media-retry.js";
-import type { InjectionMode } from "./conversation-runtime-assembly.js";
+} from "../../../daemon/conversation-media-retry.js";
+import type { InjectionMode } from "../../../daemon/conversation-runtime-assembly.js";
+import type { Message } from "../../../providers/types.js";
+import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+import { getLogger } from "../../../util/logger.js";
+import { defaultCompact, defaultEmergencyCompact } from "./compact.js";
+import type {
+  ContextWindowCompactOptions,
+  ContextWindowResult,
+} from "./window-manager.js";
+
+const log = getLogger("context-overflow-reducer");
 
 /**
  * Identifies which reduction tier was applied in a given step.
  */
 export type ReducerTier =
+  | "emergency_compaction"
   | "forced_compaction"
   | "tool_result_truncation"
   | "media_stubbing"
-  | "injection_downgrade";
+  | "injection_downgrade"
+  | "auto_compress_latest_turn";
+
+/**
+ * The "middle tiers" — the rungs bounded by `maxMiddleTierAttempts`. The
+ * emergency and auto-compress rungs are intentionally excluded so they remain
+ * reachable regardless of how small the middle-tier budget is.
+ */
+const MIDDLE_TIERS: readonly ReducerTier[] = [
+  "forced_compaction",
+  "tool_result_truncation",
+  "media_stubbing",
+  "injection_downgrade",
+];
 
 /**
  * Tracks the cumulative state of the reducer across successive calls.
@@ -94,18 +122,35 @@ export interface ReducerConfig {
   targetTokens: number;
   /** Pre-computed tool token budget to include in estimations. */
   toolTokenBudget?: number;
+  /**
+   * Conversation whose {@link ContextWindowManager} the compaction rungs
+   * resolve from the compaction store to run the summary call.
+   */
+  conversationId: string;
+  /** Per-conversation inference-profile override for the summary call. */
+  overrideProfile?: string | null;
+  /** Trust class of the actor whose turn triggered overflow recovery. */
+  actorTrustClass?: TrustClass;
+  /**
+   * The provider-reported estimate at the overflow that triggered recovery.
+   * Sizes the emergency summarize-around-last-tool-pair cut.
+   */
+  previousEstimatedInputTokens: number;
+  /**
+   * Maximum number of middle-tier reductions (forced compaction, tool-result
+   * truncation, media stubbing, injection downgrade) to apply before
+   * escalating to the terminal auto-compress rung. The emergency and
+   * auto-compress rungs are not counted against this budget.
+   */
+  maxMiddleTierAttempts: number;
+  /**
+   * Whether the terminal auto-compress-latest-turn rung is permitted. The
+   * caller resolves this from the overflow policy; when false, the ladder ends
+   * once the middle tiers are exhausted.
+   */
+  allowAutoCompressLatestTurn: boolean;
 }
 
-/**
- * Compaction callback — the reducer does not own the ContextWindowManager
- * instance, so the caller provides a function that performs compaction.
- */
-export type CompactFn = (
-  messages: Message[],
-  signal: AbortSignal | undefined,
-  options: ContextWindowCompactOptions,
-) => Promise<ContextWindowResult>;
-
 // Aggressive truncation cap for tool results during overflow recovery.
 // Much tighter than the normal per-result budget.
 const OVERFLOW_TOOL_RESULT_MAX_CHARS = 4_000;
@@ -121,53 +166,163 @@ export async function reduceContextOverflow(
   messages: Message[],
   config: ReducerConfig,
   state: ReducerState | undefined,
-  compactFn: CompactFn,
   signal?: AbortSignal,
 ): Promise<ReducerStepResult> {
   const applied = state?.appliedTiers ?? [];
+  const step = await selectNextRung(messages, config, state, applied, signal);
 
-  // Tier 1: forced compaction
-  if (!applied.includes("forced_compaction")) {
-    return applyForcedCompaction(messages, config, applied, compactFn, signal);
-  }
+  // Exhaustion is decided centrally from the rungs applied so far so the last
+  // rung that actually runs sets `exhausted`, avoiding a wasted no-op rerun.
+  step.state.exhausted = isLadderExhausted(step.state.appliedTiers, config);
+  return step;
+}
 
-  // Tier 2: aggressive tool-result truncation
-  if (!applied.includes("tool_result_truncation")) {
-    return applyToolResultTruncation(messages, config, applied, state);
+async function selectNextRung(
+  messages: Message[],
+  config: ReducerConfig,
+  state: ReducerState | undefined,
+  applied: ReducerTier[],
+  signal?: AbortSignal,
+): Promise<ReducerStepResult> {
+  // Rung 0: emergency summarize-around-last-tool-pair (uncounted, runs first).
+  if (!applied.includes("emergency_compaction")) {
+    return applyEmergencyCompaction(messages, config, applied, signal);
   }
 
-  // Tier 3: media/file payload stubbing
-  if (!applied.includes("media_stubbing")) {
-    return applyMediaStubbing(messages, config, applied, state);
+  // Middle tiers (rungs 1–4), bounded by the configured attempt budget.
+  const middleApplied = applied.filter((t) => MIDDLE_TIERS.includes(t)).length;
+  if (
+    middleApplied < config.maxMiddleTierAttempts &&
+    hasUnappliedMiddleTier(applied)
+  ) {
+    if (!applied.includes("forced_compaction")) {
+      return applyForcedCompaction(messages, config, applied, signal);
+    }
+    if (!applied.includes("tool_result_truncation")) {
+      return applyToolResultTruncation(messages, config, applied, state);
+    }
+    if (!applied.includes("media_stubbing")) {
+      return applyMediaStubbing(messages, config, applied, state);
+    }
+    return applyInjectionDowngrade(messages, config, applied, state);
   }
 
-  // Tier 4: injection downgrade
-  if (!applied.includes("injection_downgrade")) {
-    return applyInjectionDowngrade(messages, config, applied, state);
+  // Terminal rung: auto-compress the latest turn (uncounted, policy-gated).
+  if (
+    config.allowAutoCompressLatestTurn &&
+    !applied.includes("auto_compress_latest_turn")
+  ) {
+    return applyAutoCompressLatestTurn(
+      messages,
+      config,
+      applied,
+      state,
+      signal,
+    );
   }
 
-  // All tiers exhausted
+  // No rung left to apply — return a no-op step. `reduceContextOverflow`
+  // marks it exhausted via `isLadderExhausted`.
   const estimatedTokens = estimatePromptTokens(messages, config.systemPrompt, {
     providerName: config.providerName,
     toolTokenBudget: config.toolTokenBudget,
   });
   return {
     messages,
-    tier: "injection_downgrade",
+    tier: applied[applied.length - 1] ?? "forced_compaction",
     state: {
       appliedTiers: [...applied],
       injectionMode: state?.injectionMode ?? "minimal",
+      toolResultMaxChars: state?.toolResultMaxChars,
+      compactionOptions: state?.compactionOptions,
       exhausted: true,
     },
     estimatedTokens,
   };
 }
 
+/** Whether any middle tier remains unapplied. */
+function hasUnappliedMiddleTier(applied: ReducerTier[]): boolean {
+  return MIDDLE_TIERS.some((tier) => !applied.includes(tier));
+}
+
+/**
+ * Decide whether the ladder has nothing more to try after the given rungs.
+ * The terminal auto-compress rung is the last; before it, the middle tiers
+ * are exhausted once the attempt budget is spent or every middle tier ran.
+ */
+function isLadderExhausted(
+  applied: ReducerTier[],
+  config: ReducerConfig,
+): boolean {
+  if (applied.includes("auto_compress_latest_turn")) {
+    return true;
+  }
+  const middleApplied = applied.filter((t) => MIDDLE_TIERS.includes(t)).length;
+  const middleExhausted =
+    middleApplied >= config.maxMiddleTierAttempts ||
+    !hasUnappliedMiddleTier(applied);
+  if (!middleExhausted) {
+    return false;
+  }
+  // Middle tiers are done — the ladder continues only if the terminal
+  // auto-compress rung is permitted and has not run yet.
+  return !config.allowAutoCompressLatestTurn;
+}
+
+async function applyEmergencyCompaction(
+  messages: Message[],
+  config: ReducerConfig,
+  applied: ReducerTier[],
+  signal?: AbortSignal,
+): Promise<ReducerStepResult> {
+  let result: ContextWindowResult | null = null;
+  try {
+    result = await defaultEmergencyCompact({
+      conversationId: config.conversationId,
+      messages,
+      previousEstimatedInputTokens: config.previousEstimatedInputTokens,
+      overrideProfile: config.overrideProfile ?? null,
+      signal,
+    });
+  } catch (err) {
+    // No tool pair to split on, an unparseable summary, or a provider error.
+    // Fall through to forced compaction below rather than failing recovery.
+    log.warn(
+      { err },
+      "Emergency mid-turn compaction failed; falling through to forced compaction",
+    );
+  }
+
+  if (result?.compacted) {
+    return {
+      messages: result.messages,
+      tier: "emergency_compaction",
+      state: {
+        appliedTiers: [...applied, "emergency_compaction"],
+        injectionMode: "full",
+        exhausted: false,
+      },
+      estimatedTokens: result.estimatedInputTokens,
+      compactionResult: result,
+    };
+  }
+
+  // Emergency compaction produced no reduction; continue straight to forced
+  // compaction in the same step so the caller does not waste a provider rerun
+  // on unchanged messages.
+  return applyForcedCompaction(
+    messages,
+    config,
+    [...applied, "emergency_compaction"],
+    signal,
+  );
+}
+
 async function applyForcedCompaction(
   messages: Message[],
   config: ReducerConfig,
   applied: ReducerTier[],
-  compactFn: CompactFn,
   signal?: AbortSignal,
 ): Promise<ReducerStepResult> {
   const compactionOptions: ContextWindowCompactOptions = {
@@ -175,7 +330,14 @@ async function applyForcedCompaction(
     minKeepRecentUserTurns: 0,
   };
 
-  const result = await compactFn(messages, signal, compactionOptions);
+  const result = await defaultCompact({
+    conversationId: config.conversationId,
+    messages,
+    signal,
+    ...compactionOptions,
+    overrideProfile: config.overrideProfile ?? null,
+    actorTrustClass: config.actorTrustClass,
+  });
   const nextMessages = result.compacted ? result.messages : messages;
   const estimatedTokens = result.compacted
     ? result.estimatedInputTokens
@@ -339,9 +501,55 @@ function applyInjectionDowngrade(
       injectionMode: "minimal",
       toolResultMaxChars: prevState?.toolResultMaxChars,
       compactionOptions: prevState?.compactionOptions,
-      exhausted: true,
+      exhausted: false,
+    },
+    estimatedTokens,
+  };
+}
+
+async function applyAutoCompressLatestTurn(
+  messages: Message[],
+  config: ReducerConfig,
+  applied: ReducerTier[],
+  prevState: ReducerState | undefined,
+  signal?: AbortSignal,
+): Promise<ReducerStepResult> {
+  // Force-compress the latest turn as a last resort. Shares the forced
+  // compaction options, but runs after the middle tiers have been spent.
+  const compactionOptions: ContextWindowCompactOptions = {
+    force: true,
+    minKeepRecentUserTurns: 0,
+  };
+
+  const result = await defaultCompact({
+    conversationId: config.conversationId,
+    messages,
+    signal,
+    ...compactionOptions,
+    overrideProfile: config.overrideProfile ?? null,
+    actorTrustClass: config.actorTrustClass,
+  });
+  const nextMessages = result.compacted ? result.messages : messages;
+  const estimatedTokens = result.compacted
+    ? result.estimatedInputTokens
+    : estimatePromptTokens(nextMessages, config.systemPrompt, {
+        providerName: config.providerName,
+        toolTokenBudget: config.toolTokenBudget,
+      });
+
+  const nextApplied: ReducerTier[] = [...applied, "auto_compress_latest_turn"];
+  return {
+    messages: nextMessages,
+    tier: "auto_compress_latest_turn",
+    state: {
+      appliedTiers: nextApplied,
+      injectionMode: prevState?.injectionMode ?? "full",
+      toolResultMaxChars: prevState?.toolResultMaxChars,
+      compactionOptions,
+      exhausted: false,
     },
     estimatedTokens,
+    compactionResult: result,
   };
 }
 

package/src/plugins/defaults/compaction/corrected-target.ts

@@ -0,0 +1,53 @@
+/**
+ * Corrected compaction target for reactive context-overflow recovery.
+ *
+ * When the provider rejects a request as context-too-large, the rejection
+ * reveals the *actual* token count it measured (e.g. "242201 tokens > 200000").
+ * The local estimator that gated the call may have significantly under-counted,
+ * so compacting to the nominal preflight budget would still overshoot the
+ * provider's real limit and re-reject. Scaling the preflight budget down by the
+ * observed estimator error yields a target that, once the estimator re-measures
+ * the reduced history, lands under the provider's true ceiling.
+ */
+
+/** The compaction target plus the estimator-error context used to derive it. */
+export interface CorrectedOverflowTarget {
+  /**
+   * Token budget the reducer should compact below. Equal to `preflightBudget`
+   * when the estimator did not under-count, and lower otherwise.
+   */
+  targetTokens: number;
+  /**
+   * The provider-actual / estimator ratio when the estimator under-counted
+   * (> 1), otherwise `null`. Exposed so callers can log the adjustment without
+   * recomputing it.
+   */
+  estimationErrorRatio: number | null;
+}
+
+/**
+ * Compute the compaction target for an overflow rejection, lowering the
+ * preflight budget in proportion to how badly the estimator under-counted.
+ *
+ * @param preflightBudget The nominal target the estimator gates against.
+ * @param actualTokens    Provider-reported token count from the rejection, or
+ *                        `null` when it could not be parsed.
+ * @param estimatedTokens The estimator's count for the same history at overflow.
+ */
+export function computeCorrectedOverflowTarget(params: {
+  preflightBudget: number;
+  actualTokens: number | null;
+  estimatedTokens: number;
+}): CorrectedOverflowTarget {
+  const { preflightBudget, actualTokens, estimatedTokens } = params;
+  if (actualTokens != null && actualTokens > 0 && estimatedTokens > 0) {
+    const estimationErrorRatio = actualTokens / estimatedTokens;
+    if (estimationErrorRatio > 1.0) {
+      return {
+        targetTokens: Math.floor(preflightBudget / estimationErrorRatio),
+        estimationErrorRatio,
+      };
+    }
+  }
+  return { targetTokens: preflightBudget, estimationErrorRatio: null };
+}

package/src/plugins/defaults/compaction/manager-store.ts

@@ -0,0 +1,57 @@
+/**
+ * Per-conversation {@link ContextWindowManager} ownership for the default
+ * compaction module.
+ *
+ * Construction of the manager lives here rather than in the conversation so the
+ * compaction surface owns the manager's lifetime: {@link createContextWindowManager}
+ * builds the instance and records it in a per-conversation store, and
+ * {@link disposeContextWindowManager} drops it when the conversation is torn
+ * down so the store doesn't grow unbounded.
+ *
+ * This module is side-effect free: importing it only initializes an empty
+ * store and registers no plugin.
+ */
+
+import {
+  ContextWindowManager,
+  type ContextWindowManagerOptions,
+} from "./window-manager.js";
+
+/** Live managers keyed by conversation id. */
+const managersByConversation = new Map<string, ContextWindowManager>();
+
+/**
+ * Build the conversation's {@link ContextWindowManager} and register it under
+ * its conversation id. Construction is owned by the compaction module; the
+ * conversation supplies the provider, prompt/tool resolvers, and initial
+ * config. Replaces any prior manager for the same conversation so each
+ * construction yields a fresh instance, matching a direct `new` call.
+ */
+export function createContextWindowManager(
+  options: ContextWindowManagerOptions & { conversationId: string },
+): ContextWindowManager {
+  const manager = new ContextWindowManager(options);
+  managersByConversation.set(options.conversationId, manager);
+  return manager;
+}
+
+/**
+ * Resolve the manager registered for a conversation, or `undefined` when none
+ * is registered (the conversation was never constructed or has been torn
+ * down). The store is the single owner of the instance; the conversation, its
+ * agent loop, and the compaction surface all read through this lookup rather
+ * than holding their own handle.
+ */
+export function getContextWindowManager(
+  conversationId: string,
+): ContextWindowManager | undefined {
+  return managersByConversation.get(conversationId);
+}
+
+/**
+ * Release the manager registered for a conversation. Called from conversation
+ * teardown so the store releases the instance once the conversation is gone.
+ */
+export function disposeContextWindowManager(conversationId: string): void {
+  managersByConversation.delete(conversationId);
+}

package/src/plugins/defaults/compaction/package.json

@@ -1,11 +1,10 @@
 {
   "name": "default-compaction",
   "version": "1.0.0",
-  "description": "First-party default plugin wrapping the assistant's built-in compaction pipeline with a passthrough implementation.",
+  "description": "First-party default plugin providing the assistant's built-in conversation-history compaction.",
   "private": true,
   "license": "MIT",
   "type": "module",
-  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },