@animalabs/context-manager 0.5.5 → 0.5.9

package/src/adaptive/picker.ts

@@ -99,6 +99,14 @@ export interface PickerChunk {
    * by walking parentId pointers in the summary tree.
    */
   l1Id?: SummaryId;
+  /**
+   * Salience ∈ [0,1] — the coefficient on this chunk's information loss
+   * (design §13.3). Lower = folds earlier and costs less when folded:
+   * content whose payload is externalized (code on disk, tool output,
+   * images, link drops) vs conversation that exists nowhere else. Default 1.
+   * Honored by the kv-stable controller; never overrides hard protections.
+   */
+  salience?: number;
 }
 
 export interface PickerInputs {

package/src/adaptive/strategies/kv-stable.ts

@@ -30,14 +30,16 @@ import type {
 } from '../folding-strategy.js';
 import type { PickerInputs } from '../picker.js';
 import { SummaryTree } from '../summary-tree.js';
-import { planControlledFrontier } from '../kv-control.js';
+import { planControlledFrontier, type ControlPlan } from '../kv-control.js';
 
 export interface KvStableOptions {
-  /** Per-turn divergence reach — the structural perturbation cap P, in tokens.
-   *  Smaller = gentler per-turn KV churn (shallow divergence) but less efficient
-   *  compression. Exceeded only to stay under the hard wall. Default: the hard
-   *  budget (effectively unbounded within the window). */
+  /** Trust region P on per-turn perturbation, in tokens the provider would
+   *  re-read (exact kvCost — see design §13.4). Within it the solver adopts
+   *  the relevance-ideal cut; beyond it it amortizes via suffix adoption or
+   *  overrides with cause. Default: the hard budget (never binds). */
   reachTokens?: number;
+  /** Quality-gap override threshold (design §13.4). Default 0.35. */
+  qualityGapRatio?: number;
   /** Base-k summary grouping (matches the strategy's mergeThreshold). Default 6. */
   mergeThreshold?: number;
 }
@@ -49,6 +51,7 @@ export class KvStableStrategy implements FoldingStrategy {
   private readonly opts: KvStableOptions;
   private readonly fPrev: Map<ChunkId, number>;
   private target: Map<ChunkId, number> | null = null;
+  private _lastPlan: ControlPlan | null = null;
 
   constructor(inputs: PickerInputs, opts: KvStableOptions = {}) {
     this.inputs = inputs;
@@ -66,6 +69,13 @@ export class KvStableStrategy implements FoldingStrategy {
     return this.target;
   }
 
+  /** The full control plan behind the target (perturbation, override) — for
+   *  observability at the call site (`[kv-escalation]` logging). Null before
+   *  the first `selectNextFold`. */
+  lastPlan(): ControlPlan | null {
+    return this._lastPlan;
+  }
+
   private solve(budget: FoldingBudget): Map<ChunkId, number> {
     const tree = new SummaryTree(this.inputs);
 
@@ -119,23 +129,25 @@ export class KvStableStrategy implements FoldingStrategy {
       }
     }
 
-    return planControlledFrontier(this.inputs, tree, {
+    const plan = planControlledFrontier(this.inputs, tree, {
       previous: this.fPrev,
-      // Bidirectional within the slack band: fold when over the hard budget,
-      // un-fold to use headroom when under the soft target. Both reach-bounded;
-      // [targetBudget, totalBudget] is the quiet dead band.
+      // Single-path solve (design §13.4): the [targetBudget, totalBudget] band
+      // is the quiet dead band; the trust region and overrides do the rest.
       foldAtTokens: budget.totalBudget,
       expandAtTokens: budget.targetBudget,
       targetTokens: budget.targetBudget,
       windowTokens: budget.totalBudget,
       reachTokens: this.opts.reachTokens,
+      qualityGapRatio: this.opts.qualityGapRatio,
       rawZone,
       frozen,
       fixedLevels,
       pinCaps,
       now,
       mergeThreshold: this.opts.mergeThreshold,
-    }).resolutions;
+    });
+    this._lastPlan = plan;
+    return plan.resolutions;
   }
 
   /** Emit one op moving the live state toward the target frontier. */

package/src/context-log.ts

@@ -323,6 +323,17 @@ export class ContextLog {
   }
 
   private getInternal(index: number): ContextEntryInternal | null {
+    // Point lookup through chronicle's per-item cache — O(item size).
+    // See MessageStore.getInternal for why this must never fetch the
+    // full state per index.
+    //
+    // Feature-detect: getStateItemJson landed in chronicle 0.2.2; boxes
+    // still on <= 0.2.1 (npm copies) fall back to the full-materialization
+    // path so a routine `git pull` of this package can never crash them.
+    if (typeof (this.store as { getStateItemJson?: unknown }).getStateItemJson === 'function') {
+      const item = this.store.getStateItemJson(this.stateId, index);
+      return (item as ContextEntryInternal | null) ?? null;
+    }
     const all = this.getAllInternal();
     return all[index] ?? null;
   }

package/src/context-manager.ts

@@ -1,5 +1,5 @@
 import { JsStore } from '@animalabs/chronicle';
-import type { Membrane, NormalizedMessage, ContentBlock } from '@animalabs/membrane';
+import type { Membrane, NormalizedMessage, ContentBlock, ToolDefinition } from '@animalabs/membrane';
 import type {
   MessageId,
   Sequence,
@@ -23,7 +23,7 @@ import type {
 } from './types/index.js';
 import { isResettableStrategy, isPinnableStrategy, isSearchableStrategy, isRenderStatsCapable } from './types/index.js';
 import type { RenderStats } from './types/index.js';
-import { MessageStore, MessageStoreEvent } from './message-store.js';
+import { MessageStore, MessageStoreEvent, MessageStoreListener, MessageWindow, MessageWindowOptions } from './message-store.js';
 import { ContextLog } from './context-log.js';
 import { PassthroughStrategy } from './strategies/passthrough.js';
 import { splitMixedToolMessages } from './normalize-tool-messages.js';
@@ -301,6 +301,31 @@ export class ContextManager {
     return this.messageStore.getAll();
   }
 
+  /**
+   * Get the total number of messages — O(1).
+   */
+  getMessageCount(): number {
+    return this.messageStore.length();
+  }
+
+  /**
+   * Get a window of messages by slot index — O(window), not O(all).
+   * See MessageStore.getWindow for options (blob resolution, bodyGroup
+   * alignment). Intended for viewers/paginated UIs.
+   */
+  getMessageWindow(offset: number, limit: number, opts?: MessageWindowOptions): MessageWindow {
+    return this.messageStore.getWindow(offset, limit, opts);
+  }
+
+  /**
+   * Subscribe to message-store mutations (add/edit/remove/removeRange).
+   * Returns a detacher. Unlike trace events, this fires for ALL stored
+   * messages including assistant turns and tool results.
+   */
+  onMessage(listener: MessageStoreListener): () => void {
+    return this.messageStore.addListener(listener);
+  }
+
   /**
    * Query messages by filter criteria.
    * Useful for finding messages from external sources, by participant, etc.
@@ -769,7 +794,22 @@ export class ContextManager {
     }
   }
 
+  /**
+   * Live tool definitions for the owning agent, refreshed by the host on
+   * every activation (Agent.buildActivationRequest in agent-framework).
+   * Threaded into StrategyContext so compression/summarizer LLM calls can
+   * declare the same tools as the live instance — required to avoid
+   * reasoning_extraction refusals on transcripts containing tool blocks.
+   */
+  private toolDefinitions?: ToolDefinition[];
+
+  /** Host hook: record the agent's current tool definitions (see above). */
+  setToolDefinitions(tools: ToolDefinition[] | undefined): void {
+    if (tools && tools.length > 0) this.toolDefinitions = tools;
+  }
+
   private createStrategyContext(): StrategyContext {
+    const self = this;
     return {
       messageStore: this.messageStore.createView(),
       contextLog: this.contextLog.createView(),
@@ -777,6 +817,12 @@ export class ContextManager {
       currentSequence: this.store.currentSequence(),
       store: this.store,
       namespace: this.strategyNamespace,
+      // Live getter, not a snapshot: strategies capture a ctx object once and
+      // reuse it across a long-running drain (driveSpeculativeDrain recurses
+      // with the same ctx). A snapshot taken before the session's first
+      // activation would freeze `tools` as undefined for the drain's entire
+      // lifetime — the getter always reflects the latest activation.
+      get tools() { return self.toolDefinitions; },
     };
   }
 

package/src/index.ts

@@ -7,13 +7,14 @@ export { phaseChannel, enterPhase, withPhase, withPhaseAsync } from './phase-cha
 
 // Storage
 export { MessageStore } from './message-store.js';
-export type { MessageStoreEvent, MessageStoreListener } from './message-store.js';
+export type { MessageStoreEvent, MessageStoreListener, MessageWindow, MessageWindowOptions } from './message-store.js';
+export { concatBodyGroups } from './adaptive/render.js';
 export { ContextLog } from './context-log.js';
 export { BlobManager } from './blob-manager.js';
 
 // Strategies
 export { PassthroughStrategy } from './strategies/passthrough.js';
-export { AutobiographicalStrategy, type AutobiographicalProgressSnapshot } from './strategies/autobiographical.js';
+export { AutobiographicalStrategy, type AutobiographicalProgressSnapshot, type Chunk } from './strategies/autobiographical.js';
 export { KnowledgeStrategy } from './strategies/knowledge.js';
 
 // Utilities

package/src/message-store.ts

@@ -28,6 +28,39 @@ export type MessageStoreEvent =
  */
 export type MessageStoreListener = (event: MessageStoreEvent) => void;
 
+/**
+ * Options for windowed message reads.
+ */
+export interface MessageWindowOptions {
+  /**
+   * Re-inline blob media (images/documents) into content blocks, matching
+   * the behavior of get()/getAll(). Default true. Viewers that only need
+   * text/thinking/tool blocks should pass false to avoid inflating large
+   * base64 payloads.
+   */
+  resolveBlobs?: boolean;
+  /**
+   * Extend the window edges outward so that no bodyGroup (shard run of a
+   * single large message) is split across the window boundary. Default
+   * false (exact offset/limit semantics).
+   */
+  alignToBodyGroups?: boolean;
+}
+
+/**
+ * A window of messages plus enough metadata to page through the store.
+ */
+export interface MessageWindow {
+  messages: StoredMessage[];
+  /**
+   * Actual first slot index of the returned window. May be lower than the
+   * requested offset when alignToBodyGroups extended the window backward.
+   */
+  startIndex: number;
+  /** Total number of messages in the store at read time. */
+  totalCount: number;
+}
+
 /**
  * Options for token estimation.
  */
@@ -358,19 +391,72 @@ export class MessageStore {
     );
   }
 
+  /**
+   * Get a window of messages by slot index — O(window), not O(all).
+   *
+   * Backed by chronicle's `getStateSlice` (0.2.2+) with a
+   * full-materialization fallback for older chronicle copies, mirroring
+   * the feature-detect in getInternal().
+   */
+  getWindow(offset: number, limit: number, opts: MessageWindowOptions = {}): MessageWindow {
+    const totalCount = this.length();
+    let start = Math.max(0, Math.min(offset, totalCount));
+    let end = Math.min(start + Math.max(0, limit), totalCount);
+
+    if (start >= end) {
+      return { messages: [], startIndex: Math.min(start, totalCount), totalCount };
+    }
+
+    if (opts.alignToBodyGroups) {
+      // Shards of a bodyGroup are contiguous by construction (removeRange
+      // refuses to bisect a group). Walk edges outward with O(item) point
+      // lookups until the group boundary.
+      const first = this.getInternal(start);
+      if (first?.bodyGroupId !== undefined) {
+        while (start > 0) {
+          const prev = this.getInternal(start - 1);
+          if (prev?.bodyGroupId !== first.bodyGroupId) break;
+          start--;
+        }
+      }
+      const last = this.getInternal(end - 1);
+      if (last?.bodyGroupId !== undefined) {
+        while (end < totalCount) {
+          const next = this.getInternal(end);
+          if (next?.bodyGroupId !== last.bodyGroupId) break;
+          end++;
+        }
+      }
+    }
+
+    const internals = this.getSliceInternal(start, end - start);
+    const resolveBlobs = opts.resolveBlobs !== false;
+    return {
+      messages: internals.map((internal, i) =>
+        this.internalToStored(internal, internal.id, start + i, resolveBlobs)
+      ),
+      startIndex: start,
+      totalCount,
+    };
+  }
+
   /**
    * Get messages from a specific index.
+   * Negative indices count from the end, matching Array.prototype.slice.
    */
   getFrom(index: number): StoredMessage[] {
-    return this.getAll().slice(index);
+    const len = this.length();
+    const start = index < 0 ? Math.max(0, len + index) : Math.min(index, len);
+    return this.getWindow(start, len - start).messages;
   }
 
   /**
    * Get the last N messages.
    */
   getTail(count: number): StoredMessage[] {
-    const all = this.getAll();
-    return all.slice(Math.max(0, all.length - count));
+    const len = this.length();
+    const n = Math.max(0, Math.min(count, len));
+    return this.getWindow(len - n, n).messages;
   }
 
   /**
@@ -391,21 +477,62 @@ export class MessageStore {
     return tokens;
   }
 
+  /**
+   * Closed-loop calibration multiplier applied to every estimate (default 1).
+   * Owned by the strategy: it compares real `usage` totals against the
+   * compile-time estimate and feeds the EMA back here, so the store's
+   * numbers track the live model/content mix instead of a fixed heuristic.
+   */
+  private tokenCalibration = 1;
+
+  setTokenCalibration(factor: number): void {
+    if (Number.isFinite(factor) && factor > 0.25 && factor < 4) this.tokenCalibration = factor;
+  }
+
+  getTokenCalibration(): number {
+    return this.tokenCalibration;
+  }
+
+  /**
+   * Hidden-CoT price for a signed thinking block whose text was summarized/
+   * redacted away (2026-07-12): the block estimates as EMPTY client-side, but
+   * signed replay bills the FULL original chain of thought. Measured on
+   * mythos production turns: median ~608 tokens/block, mean ~590, p90 ~1210.
+   * A per-block `tokenEstimate` stamped at creation (from usage residuals)
+   * takes precedence; this constant is the fallback for unstamped history.
+   */
+  static readonly HIDDEN_THINKING_TOKENS_DEFAULT = 600;
+
   private estimateBlockTokens(block: ContentBlock): number {
+    return Math.round(this.estimateBlockTokensRaw(block) * this.tokenCalibration);
+  }
+
+  private estimateBlockTokensRaw(block: ContentBlock): number {
     switch (block.type) {
       case 'text':
         return this.tokenEstimator(block.text);
-      case 'thinking':
+      case 'thinking': {
+        // Stamped price wins; a signed-but-empty block is a HIDDEN full CoT
+        // (never "no thinking") — price it at the measured default.
+        const stamped = (block as { tokenEstimate?: number }).tokenEstimate;
+        if (typeof stamped === 'number') return stamped;
+        const hasSignature =
+          typeof (block as { signature?: string }).signature === 'string' &&
+          ((block as { signature?: string }).signature as string).length > 0;
+        if (hasSignature && (!block.thinking || block.thinking.length === 0)) {
+          return MessageStore.HIDDEN_THINKING_TOKENS_DEFAULT;
+        }
         return this.tokenEstimator(block.thinking);
+      }
       case 'tool_use':
-        return this.tokenEstimator(JSON.stringify(block.input)) + 20; // overhead for name, id
+        return jsonTokenEstimator(JSON.stringify(block.input)) + 20; // overhead for name, id
       case 'tool_result':
         if (!block.content) return 0;
         if (typeof block.content === 'string') {
-          return this.tokenEstimator(block.content);
+          return jsonTokenEstimator(block.content);
         }
         if (Array.isArray(block.content)) {
-          return block.content.reduce((sum, b) => sum + this.estimateBlockTokens(b), 0);
+          return block.content.reduce((sum, b) => sum + this.estimateBlockTokensRaw(b), 0);
         }
         return 0;
       case 'image':
@@ -429,6 +556,8 @@ export class MessageStore {
       getFrom: (index) => this.getFrom(index),
       getTail: (count) => this.getTail(count),
       length: () => this.length(),
+      setTokenCalibration: (f: number) => this.setTokenCalibration(f),
+      getTokenCalibration: () => this.getTokenCalibration(),
       estimateTokens: (msg) => this.estimateTokens(msg),
     };
   }
@@ -545,7 +674,35 @@ export class MessageStore {
     return state as StoredMessageInternal[];
   }
 
+  private getSliceInternal(offset: number, limit: number): StoredMessageInternal[] {
+    // Windowed read — O(window) JSON conversion instead of materializing
+    // the entire state slot. getStateSlice landed in chronicle 0.2.2 and
+    // returns the window as a JSON-array Buffer; feature-detect so boxes
+    // on <= 0.2.1 fall back to full materialization (same pattern as
+    // getInternal below).
+    const s = this.store as { getStateSlice?: (id: string, offset: number, limit: number) => Buffer | null };
+    if (typeof s.getStateSlice === 'function') {
+      const buf = s.getStateSlice(this.stateId, offset, limit);
+      if (!buf) return [];
+      return JSON.parse(buf.toString('utf-8')) as StoredMessageInternal[];
+    }
+    return this.getAllInternal().slice(offset, offset + limit);
+  }
+
   private getInternal(index: number): StoredMessageInternal | null {
+    // Point lookup through chronicle's per-item cache — O(item size).
+    // Never fetch the full state for a single index: with a 4.6k-message
+    // session, each full `getStateJson` materialization cost ~15ms, and
+    // per-entry get() loops turned renders into minutes (observed on
+    // Lena, 2026-07-02, /debug/context at 51–108s).
+    //
+    // Feature-detect: getStateItemJson landed in chronicle 0.2.2; boxes
+    // still on <= 0.2.1 (npm copies) fall back to the full-materialization
+    // path so a routine `git pull` of this package can never crash them.
+    if (typeof (this.store as { getStateItemJson?: unknown }).getStateItemJson === 'function') {
+      const item = this.store.getStateItemJson(this.stateId, index);
+      return (item as StoredMessageInternal | null) ?? null;
+    }
     const all = this.getAllInternal();
     return all[index] ?? null;
   }
@@ -554,6 +711,7 @@ export class MessageStore {
     internal: StoredMessageInternal,
     id: MessageId,
     _index: number,
+    resolveBlobs: boolean = true,
   ): StoredMessage {
     const stored: StoredMessage = {
       id,
@@ -570,7 +728,12 @@ export class MessageStore {
       // so /undo of a 800-message conversation forked ~400 messages back.
       sequence: internal.sequence,
       participant: internal.participant,
-      content: this.blobManager.resolveBlobs(internal.content),
+      // When resolveBlobs is false, blob_ref placeholder blocks are passed
+      // through un-inflated (StoredContentBlock ⊂ wire-safe superset of
+      // ContentBlock for viewer purposes).
+      content: resolveBlobs
+        ? this.blobManager.resolveBlobs(internal.content)
+        : (internal.content as unknown as ContentBlock[]),
       metadata: internal.metadata,
       timestamp: new Date(internal.timestamp),
       causedBy: internal.causedBy,
@@ -587,6 +750,36 @@ export class MessageStore {
 /**
  * Default token estimator: chars / 4
  */
+/**
+ * Content-class token rates (2026-07-12, measured on mythos production
+ * requests by reconciling real `usage` against per-class char counts):
+ *   - prose (Discord multiparty, markdown, emoji)  ≈ 2.9 chars/token
+ *   - JSON / tool i/o / code                        ≈ 2.3 chars/token
+ * The old flat chars/4 under-priced real windows by ~1.7-1.9x (a 183.6k
+ * "hard budget" compiled to a 344k request — straight into the refusal
+ * band). Rates are deliberately slightly conservative; the closed-loop
+ * calibration multiplier trims the residual per agent.
+ */
+const PROSE_CHARS_PER_TOKEN = 2.9;
+const DENSE_CHARS_PER_TOKEN = 2.3;
+
 function defaultTokenEstimator(text: string): number {
-  return Math.ceil(text.length / 4);
+  if (!text) return 0;
+  // Cheap density probe: JSON/code punctuation and non-ASCII share.
+  let dense = 0;
+  const n = Math.min(text.length, 2000);
+  for (let i = 0; i < n; i++) {
+    const c = text.charCodeAt(i);
+    if (c > 126) { dense++; continue; } // non-ASCII (emoji, accents, CJK)
+    const ch = text[i];
+    if (ch === '{' || ch === '}' || ch === '[' || ch === ']' || ch === '"' || ch === ':' || ch === '_' || ch === '/' || ch === '=' || ch === '`') dense++;
+  }
+  const rate = dense / n > 0.12 ? DENSE_CHARS_PER_TOKEN : PROSE_CHARS_PER_TOKEN;
+  return Math.ceil(text.length / rate);
+}
+
+/** JSON-ish payloads (tool inputs/results) always use the dense rate. */
+function jsonTokenEstimator(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / DENSE_CHARS_PER_TOKEN);
 }