@animalabs/context-manager 0.5.4 → 0.5.9

package/src/strategies/index.ts

@@ -1,2 +1,2 @@
 export { PassthroughStrategy } from './passthrough.js';
-export { AutobiographicalStrategy, type AutobiographicalProgressSnapshot } from './autobiographical.js';
+export { AutobiographicalStrategy, type AutobiographicalProgressSnapshot, type Chunk } from './autobiographical.js';

package/src/strategies/knowledge.ts

@@ -41,6 +41,17 @@ export class KnowledgeStrategy extends AutobiographicalStrategy {
   // Override: Semantic chunking
   // ============================================================================
 
+  /**
+   * KnowledgeStrategy keeps the legacy recompute-every-rebuild chunker:
+   * its chunk boundaries are semantic (phase transitions), recomputed from
+   * message content, and its stores are offline mining artifacts — the
+   * restart-duplication failure mode that chunk persistence fixes does not
+   * apply, and persisted token-sum records would fight the phase chunker.
+   */
+  protected get chunkPersistenceEnabled(): boolean {
+    return false;
+  }
+
   protected rebuildChunks(store: MessageStoreView): void {
     const messagesToChunk = this.getCompressibleMessages(store);
 
@@ -81,7 +92,20 @@ export class KnowledgeStrategy extends AutobiographicalStrategy {
       const phaseChanged = currentPhase !== null && phase !== currentPhase;
       const maxTokens = this.getMaxChunkTokens(currentPhase ?? phase);
       const sizeExceeded = currentTokens >= maxTokens;
-      const shouldClose = currentChunk.length >= 2 && (phaseChanged || sizeExceeded);
+      // Same tool-pair boundary guard as the base chunker (rebuildChunks in
+      // AutobiographicalStrategy): never close a chunk whose LAST message
+      // contains a tool_use block — its matching tool_result lives in the
+      // immediately-following message (the one about to be pushed). Closing
+      // here would split the pair across chunks; when the earlier chunk
+      // compresses first, the raw orphan tool_result renders unpaired and
+      // the Anthropic API rejects the request. Deferring the close by one
+      // iteration pulls the tool_result into the same chunk. (Phase never
+      // changes between a tool_use and its tool_result — the result inherits
+      // lastToolPhase — so this defers sizeExceeded closes in practice.)
+      const shouldClose =
+        currentChunk.length >= 2 &&
+        (phaseChanged || sizeExceeded) &&
+        !this.lastMessageContainsToolUse(currentChunk);
 
       if (shouldClose) {
         const chunk = this.createChunk(

package/src/types/index.ts

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

package/src/types/strategy.ts

@@ -1,5 +1,5 @@
 import type { JsStore } from '@animalabs/chronicle';
-import type { Membrane, ContentBlock } from '@animalabs/membrane';
+import type { Membrane, ContentBlock, ToolDefinition } from '@animalabs/membrane';
 import type { StoredMessage, MessageId, Sequence } from './message.js';
 import type { ContextEntry, TokenBudget, PendingWork } from './context.js';
 
@@ -19,6 +19,9 @@ export interface MessageStoreView {
   length(): number;
   /** Estimate tokens for a message */
   estimateTokens(message: StoredMessage): number;
+  /** Closed-loop estimator calibration (optional — MessageStore provides it). */
+  setTokenCalibration?(factor: number): void;
+  getTokenCalibration?(): number;
 }
 
 /**
@@ -43,6 +46,16 @@ export interface ContextLogView {
 export interface StrategyContext {
   /** Read-only view of message store */
   messageStore: MessageStoreView;
+  /**
+   * The agent's live tool definitions, as last supplied by the host (set on
+   * every activation via ContextManager.setToolDefinitions). Summarizer /
+   * compression requests MUST declare these: replaying a transcript full of
+   * tool_use/tool_result blocks with no `tools` param trips Anthropic's
+   * reasoning_extraction classifier (looks like a foreign agent trace being
+   * duplicated) and the whole compression pass gets deterministically
+   * refused. Optional because ticks can fire before the first activation.
+   */
+  tools?: ToolDefinition[];
   /** Read-only view of context log */
   contextLog: ContextLogView;
   /** Membrane instance for LLM calls (compression) */
@@ -186,8 +199,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>;
 }
@@ -329,6 +342,14 @@ export interface AutobiographicalConfig {
    *  this limit have their text/tool_result content truncated. 0 = no limit. */
   maxMessageTokens: number;
 
+  /**
+   * Fractional grace above the configured hard context budget before an
+   * exhausted adaptive picker rejects the compile. The solver still targets
+   * the original budget; this only absorbs coarse fold quanta and indivisible
+   * head/tail boundary overshoot. Default 0 (strict budget enforcement).
+   */
+  overBudgetGraceRatio?: number;
+
   // --- Live image policy ---
 
   /** Maximum number of images kept "live" (sent as real image blocks) in the
@@ -342,6 +363,42 @@ export interface AutobiographicalConfig {
    *  Typically much shallower than recentWindowTokens. 0 = never strip by depth. */
   imageStripDepthTokens?: number;
 
+  /**
+   * Merge grouping (2026-07-12 contiguity fix): break a merge run when the
+   * positional gap between consecutive unmerged candidates exceeds this many
+   * messages. Small holes (wiped/pruned nodes) bridge fine; cross-era gaps
+   * must not — a merge group spanning already-merged history can straddle
+   * the recent window and block its whole lineage from folding. Default 300.
+   */
+  mergeContiguityGapLimit?: number;
+
+  /**
+   * Byte wall for live images (2026-07-12): keep inline images newest-first
+   * only while their cumulative base64 size stays under this budget — on top
+   * of `maxLiveImages` / `imageStripDepthTokens`. Guarantees the compiled
+   * window fits the API's total request size cap (413 request_too_large), so
+   * membrane's oversize check is a true invariant, never a silent editor.
+   * Default 20MB (of base64; the API cap is 32MB total).
+   */
+  maxLiveImageBytes?: number;
+
+  /**
+   * Merge grouping: exclude candidates whose OWN source span exceeds this
+   * many messages (replay-era summaries can span the entire chronicle and
+   * would bridge any run they join). They stay on the frontier. Default 1500.
+   */
+  mergeMaxSourceSpanMessages?: number;
+
+  /**
+   * L1 production holdback: keep the newest N closed chunks out of the
+   * speculative compression queue (default 1). The chunk at the live edge is
+   * the one most likely to still be in motion — summarize it only once a
+   * newer chunk has closed behind it. Speculative production of everything
+   * older proceeds ahead of need as usual. A picker `produce` op (real fold
+   * demand) bypasses the holdback. 0 = compress at close (old behavior).
+   */
+  l1HoldbackChunks?: number;
+
   // Legacy aliases (deprecated, use summary* instead)
   /** @deprecated Use summarySystemPrompt */
   diarySystemPrompt?: string;
@@ -387,6 +444,20 @@ export interface AutobiographicalConfig {
    */
   compressionRecallBudgetTokens?: number;
 
+  /**
+   * Minimum substantive text (non-whitespace chars across a chunk's
+   * messages) below which L1 compression skips the LLM call and stores a
+   * mechanical stub summary instead (default: 200).
+   *
+   * A chunk of silent/skip turns and bare system traffic gives the
+   * summarizer nothing to remember; asked anyway, it confabulates —
+   * it reaches for the nearest salient content (head window, prior
+   * recall pairs) and narrates it as if it just happened (the
+   * "68 initiations" incident). Chunks containing any non-text blocks
+   * (tool cycles, images) are never stubbed. Set to 0 to disable.
+   */
+  minChunkCharsForLLM?: number;
+
   /**
    * When true (default), each selected summary emits as its own positioned
    * Q/A recall pair, sorted chronologically by source range. When false,
@@ -487,13 +558,26 @@ export interface AutobiographicalConfig {
   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.
+   * Trust region P (tokens) for `foldingStrategy: 'kv-stable'` — bounds how
+   * much prefix re-read (exact kvCost) an ordinary turn may take; the solver
+   * adopts the relevance-ideal cut within it, amortizes bigger repairs across
+   * turns (suffix adoption), and exceeds it only with a recorded override
+   * (bootstrap / infeasible / quality-gap — logged as `[kv-escalation]`).
+   * See docs/adaptive-resolution-design.md §13. Default: the hard budget
+   * (a rendered layout never exceeds it, so the default never binds).
    */
   kvStableReachTokens?: number;
 
+  /**
+   * Quality-gap override threshold for `foldingStrategy: 'kv-stable'`
+   * (design §13.4): a plan within the trust region is rejected — and the
+   * relevance-ideal cut adopted, paying the perturbation — when its
+   * salience-weighted misallocation loss exceeds the ideal's by more than
+   * this fraction of the ideal's. Also bounds how misallocated a dead-band
+   * hold may be before the solver self-heals. Default 0.35.
+   */
+  kvStableQualityGapRatio?: number;
+
   /**
    * Slack ratio (hysteresis) for the picker. The picker folds until total
    * tokens ≤ budget * (1 - slack), and stays quiet while between slack
@@ -596,6 +680,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;
 }
 
 /**