@animalabs/context-manager 0.5.3 → 0.5.5

package/src/types/index.ts

@@ -38,6 +38,7 @@ export type {
   KnowledgeConfig,
   ResettableStrategy,
   ProtectedRange,
+  PinLevelOptions,
   SearchQuery,
   SearchResult,
   SearchableStrategy,

package/src/types/strategy.ts

@@ -186,8 +186,8 @@ export function isResettableStrategy(s: ContextStrategy): s is ResettableStrateg
  * original chronological position. Implemented by AutobiographicalStrategy.
  */
 export interface PinnableStrategy extends ContextStrategy {
-  pinRange(firstMessageId: string, lastMessageId: string, opts?: { name?: string }): string;
-  markDocument(messageId: string, opts?: { name?: string }): string;
+  pinRange(firstMessageId: string, lastMessageId: string, opts?: PinLevelOptions): string;
+  markDocument(messageId: string, opts?: PinLevelOptions): string;
   unpin(pinId: string): boolean;
   listPins(): ReadonlyArray<ProtectedRange>;
 }
@@ -258,12 +258,25 @@ export function isSearchableStrategy(s: ContextStrategy): s is SearchableStrateg
 export interface RenderStats {
   head: { messages: number; tokens: number };
   tail: { messages: number; tokens: number };
+  /**
+   * Raw (L0) messages the renderer kept verbatim in the MIDDLE region — i.e.
+   * neither head nor tail. Under adaptive resolution the picker routinely keeps
+   * older messages raw at a resolution gradient; these are real context tokens
+   * that the head/tail/summary buckets don't capture. (Empty for a pure
+   * hierarchical render with no pinned/uncompressed-middle messages.)
+   */
+  middleRaw: { messages: number; tokens: number };
   summaries: {
     l1: { count: number; tokens: number };
     l2: { count: number; tokens: number };
     l3: { count: number; tokens: number };
   };
   pending: { chunks: number; merges: number };
+  /**
+   * Sum across all buckets — the actual rendered context size. A summary is a
+   * Q/A pair, so it counts as 2 messages here.
+   */
+  total: { messages: number; tokens: number };
 }
 
 /**
@@ -316,6 +329,19 @@ export interface AutobiographicalConfig {
    *  this limit have their text/tool_result content truncated. 0 = no limit. */
   maxMessageTokens: number;
 
+  // --- Live image policy ---
+
+  /** Maximum number of images kept "live" (sent as real image blocks) in the
+   *  compiled context. Counted newest-first across the whole window; images
+   *  beyond this many are replaced with a text placeholder. 0 = unlimited.
+   *  A hard ceiling for dense bursts that pack many images into the live window. */
+  maxLiveImages?: number;
+  /** Token depth from the newest message beyond which images are stripped to a
+   *  text placeholder, even though the surrounding text stays verbatim. Measured
+   *  the same way as recentWindowTokens (cumulative tokens walked from the tail).
+   *  Typically much shallower than recentWindowTokens. 0 = never strip by depth. */
+  imageStripDepthTokens?: number;
+
   // Legacy aliases (deprecated, use summary* instead)
   /** @deprecated Use summarySystemPrompt */
   diarySystemPrompt?: string;
@@ -453,9 +479,20 @@ export interface AutobiographicalConfig {
    * Folding strategy name when adaptiveResolution is on. One of:
    *   'flat-profile' (default) — level-equalizing
    *   'oldest-first' — chronological
+   *   'kv-stable' — the KV-stable context controller: minimizes real prefix
+   *     churn directly (flat zone + per-turn reach cap; no λ). Built per-compile
+   *     from the live PickerInputs. See docs/kv-stable-context-control.md.
    * Custom strategies can be plugged in by the host application.
    */
-  foldingStrategy?: 'flat-profile' | 'oldest-first';
+  foldingStrategy?: 'flat-profile' | 'oldest-first' | 'kv-stable';
+
+  /**
+   * Per-turn divergence reach (tokens) for `foldingStrategy: 'kv-stable'` — the
+   * structural KV-perturbation cap P. Smaller = gentler per-turn cache churn but
+   * less efficient compression; exceeded only to stay under the hard budget.
+   * Default: unbounded within the budget.
+   */
+  kvStableReachTokens?: number;
 
   /**
    * Slack ratio (hysteresis) for the picker. The picker folds until total
@@ -559,6 +596,35 @@ export interface ProtectedRange {
   name?: string;
   /** Creation timestamp (ms since epoch). */
   created: number;
+  /**
+   * Pin-AT-level-k (V2 dynamic pins, `docs/best-fit-frontier-resolution.md` §7).
+   * Fix the covered chunks to render at EXACTLY this fold level (0 = raw): the
+   * frontier cut passes through the L_k node — neither folded deeper nor
+   * un-folded shallower. When set, this range is NOT a classic force-raw pin.
+   * Takes precedence over `maxLevel`. Omitted → not a fixed-level pin.
+   *
+   * Honored only by the KV-stable controller (`foldingStrategy: 'kv-stable'`);
+   * other strategies fall back to treating the range as raw (a safe superset).
+   */
+  level?: number;
+  /**
+   * Pin-max-level (V2 dynamic pins): the covered chunks may fold no DEEPER than
+   * this level — raw..L_k allowed, deeper forbidden — a hard cap honored even
+   * under the window-pressure emergency. `maxLevel: 0` ≡ classic pin-raw.
+   * Ignored when `level` is set. Omitted → this pin imposes no depth cap.
+   *
+   * Honored only by the KV-stable controller; see `level`.
+   */
+  maxLevel?: number;
+}
+
+/** Optional fold-depth bounds for a V2 dynamic pin (see `ProtectedRange`). */
+export interface PinLevelOptions {
+  name?: string;
+  /** Pin AT exactly this level (0 = raw). Fixes the cut through the L_k node. */
+  level?: number;
+  /** Fold no deeper than this level (hard cap; `0` ≡ classic pin-raw). */
+  maxLevel?: number;
 }
 
 /**
@@ -623,6 +689,8 @@ Write naturally, as recollection of what you experienced.`,
   summaryContextLabel: 'What do you remember from earlier?',
   summaryParticipant: 'Claude',
   maxMessageTokens: 0,
+  maxLiveImages: 6,
+  imageStripDepthTokens: 30000,
   positionedRecallPairs: true,
   recallHeaderTemplate: '[Recall {id}]',
 };