@animalabs/context-manager 0.3.0 → 0.5.0

package/src/strategies/index.ts

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

package/src/types/index.ts

@@ -37,6 +37,19 @@ export type {
   PhaseType,
   KnowledgeConfig,
   ResettableStrategy,
+  ProtectedRange,
+  SearchQuery,
+  SearchResult,
+  SearchableStrategy,
+  PinnableStrategy,
+  RenderStats,
+  RenderStatsCapableStrategy,
 } from './strategy.js';
 
-export { DEFAULT_AUTOBIOGRAPHICAL_CONFIG, isResettableStrategy } from './strategy.js';
+export {
+  DEFAULT_AUTOBIOGRAPHICAL_CONFIG,
+  isResettableStrategy,
+  isPinnableStrategy,
+  isSearchableStrategy,
+  isRenderStatsCapable,
+} from './strategy.js';

package/src/types/message.ts

@@ -47,6 +47,40 @@ export interface StoredMessage {
   timestamp: Date;
   /** IDs of messages that caused this one (from Chronicle causation) */
   causedBy?: MessageId[];
+
+  /**
+   * If this message is a shard of a larger logical message (chunked at
+   * ingestion because it exceeded `chunkThreshold`), this is the stable
+   * group id shared with sibling shards. Shards with the same id are
+   * concatenated into one API message at render time. Null/undefined
+   * for messages that fit in a single chunk. See
+   * `docs/adaptive-resolution-design.md` §3.6.
+   */
+  bodyGroupId?: string;
+
+  /**
+   * The shard's order within its bodyGroup, starting at 0. Only meaningful
+   * when `bodyGroupId` is set. Used to reassemble shards into byte-faithful
+   * order at render time.
+   */
+  shardIndex?: number;
+
+  /**
+   * Current display resolution for this chunk:
+   *  - 0  = render raw content
+   *  - k>0 = render the L_k summary that covers this chunk
+   *
+   * Set by the picker (or the agent in V2). Default 0. See
+   * `docs/adaptive-resolution-design.md` §3.3.
+   */
+  currentResolution?: number;
+
+  /**
+   * If true, the picker must not change `currentResolution` for this chunk.
+   * Set by `lockChunk()` (programmatic API) or, in V2, by the agent's
+   * `unfold` tool. Default false.
+   */
+  lockedByAgent?: boolean;
 }
 
 /**
@@ -85,6 +119,15 @@ export interface StoredMessageInternal {
   metadata?: MessageMetadata;
   timestamp: number; // Unix timestamp for storage
   causedBy?: MessageId[];
+
+  /** See StoredMessage.bodyGroupId */
+  bodyGroupId?: string;
+  /** See StoredMessage.shardIndex */
+  shardIndex?: number;
+  /** See StoredMessage.currentResolution */
+  currentResolution?: number;
+  /** See StoredMessage.lockedByAgent */
+  lockedByAgent?: boolean;
 }
 
 /**

package/src/types/strategy.ts

@@ -1,4 +1,5 @@
-import type { Membrane } from '@animalabs/membrane';
+import type { JsStore } from '@animalabs/chronicle';
+import type { Membrane, ContentBlock } from '@animalabs/membrane';
 import type { StoredMessage, MessageId, Sequence } from './message.js';
 import type { ContextEntry, TokenBudget, PendingWork } from './context.js';
 
@@ -48,6 +49,22 @@ export interface StrategyContext {
   membrane?: Membrane;
   /** Current sequence number */
   currentSequence: Sequence;
+  /**
+   * Underlying Chronicle store. Strategies may register their own state slots
+   * (via `store.registerState`) for durable strategy state that needs to
+   * survive process restart and follow Chronicle branches.
+   *
+   * State IDs should be scoped under `namespace` to avoid collisions with
+   * other strategies or with the message/context-log states.
+   */
+  store: JsStore;
+  /**
+   * Namespace under which this strategy should scope its state IDs.
+   * Use as a prefix: e.g. `${namespace}/autobio:summaries`. Always defined;
+   * defaults to a stable per-manager value when no caller-supplied namespace
+   * exists, so strategies never need to handle the unscoped case.
+   */
+  namespace: string;
 }
 
 /**
@@ -108,6 +125,41 @@ export interface ContextStrategy {
     log: ContextLogView,
     budget: TokenBudget
   ): ContextEntry[];
+
+  /**
+   * Optional: at ingestion time, decide whether to split this incoming
+   * message into multiple shards (because it's too large to be a single
+   * fold unit). If returned, the framework stores each shard as a separate
+   * StoredMessage with the shared `bodyGroupId` and per-shard `shardIndex`,
+   * and the render path will reassemble them into one API message at
+   * compile time.
+   *
+   * Return null or undefined to skip chunking (message stored as one record).
+   *
+   * See `docs/adaptive-resolution-design.md` §3.6.
+   */
+  chunkIngressMessage?(
+    participant: string,
+    content: ContentBlock[]
+  ): IngressChunkResult | null;
+}
+
+/**
+ * Result of a strategy's ingestion-time chunking decision.
+ */
+export interface IngressChunkResult {
+  /** Stable id shared by all shards of this message. */
+  bodyGroupId: string;
+  /**
+   * The shards in source order. Each becomes a separate StoredMessage.
+   * Concatenating the shards' text content must reproduce the original
+   * message body byte-for-byte.
+   */
+  shards: Array<{
+    content: ContentBlock[];
+    /** Order within the bodyGroup, starting at 0. */
+    shardIndex: number;
+  }>;
 }
 
 /**
@@ -128,6 +180,109 @@ export function isResettableStrategy(s: ContextStrategy): s is ResettableStrateg
   return 'resetHeadWindow' in s && typeof (s as ResettableStrategy).resetHeadWindow === 'function';
 }
 
+/**
+ * Strategy that supports protected ranges (pins + documents).
+ * Pinned ranges are excluded from compression and render raw at their
+ * 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;
+  unpin(pinId: string): boolean;
+  listPins(): ReadonlyArray<ProtectedRange>;
+}
+
+/** Type guard for strategies that support pins / documents. */
+export function isPinnableStrategy(s: ContextStrategy): s is PinnableStrategy {
+  return (
+    'pinRange' in s &&
+    typeof (s as PinnableStrategy).pinRange === 'function' &&
+    'unpin' in s &&
+    typeof (s as PinnableStrategy).unpin === 'function'
+  );
+}
+
+/**
+ * Query for `searchSummaries`. At least one of `text` or `regex` should be
+ * provided to constrain results; otherwise all summaries pass.
+ */
+export interface SearchQuery {
+  /** Case-insensitive substring match against summary content. */
+  text?: string;
+  /** Regex match against summary content (overrides `text` if both set). */
+  regex?: RegExp;
+  /** Filter by summary level(s). Default: all levels. */
+  levels?: SummaryLevel[];
+  /** Maximum number of results to return. Default: 50. */
+  limit?: number;
+  /**
+   * Include summaries that have been merged into a higher-level summary.
+   * Default: false (only "live" unmerged summaries are returned).
+   */
+  includeMerged?: boolean;
+}
+
+/** Result of a single search match. */
+export interface SearchResult {
+  summary: SummaryEntry;
+  /** Number of times the query pattern matched in the summary content. */
+  matches: number;
+}
+
+/**
+ * Strategy that supports searching its summary archive. Implemented by
+ * AutobiographicalStrategy.
+ */
+export interface SearchableStrategy extends ContextStrategy {
+  searchSummaries(query: SearchQuery): SearchResult[];
+  getSummary(id: string): SummaryEntry | null;
+}
+
+/** Type guard for strategies that support search. */
+export function isSearchableStrategy(s: ContextStrategy): s is SearchableStrategy {
+  return (
+    'searchSummaries' in s &&
+    typeof (s as SearchableStrategy).searchSummaries === 'function' &&
+    'getSummary' in s &&
+    typeof (s as SearchableStrategy).getSummary === 'function'
+  );
+}
+
+/**
+ * Per-render observability stats from a strategy. Counts and token sums for
+ * head / tail / summaries / pending work, suitable for TUIs and dashboards
+ * that want to display "how much of the context is folded vs raw" at a
+ * glance. Token sums use the strategy's own estimates so they line up with
+ * the numbers `select()` uses for budget math.
+ */
+export interface RenderStats {
+  head: { messages: number; tokens: number };
+  tail: { 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 };
+}
+
+/**
+ * Strategy that can produce render-time observability stats. Implemented by
+ * AutobiographicalStrategy. Optional capability — strategies that don't
+ * implement it simply have `ContextManager.getRenderStats()` return `null`.
+ */
+export interface RenderStatsCapableStrategy extends ContextStrategy {
+  getRenderStats(store: MessageStoreView): RenderStats;
+}
+
+/** Type guard for strategies that produce render stats. */
+export function isRenderStatsCapable(s: ContextStrategy): s is RenderStatsCapableStrategy {
+  return (
+    'getRenderStats' in s &&
+    typeof (s as RenderStatsCapableStrategy).getRenderStats === 'function'
+  );
+}
+
 /**
  * Configuration for the Autobiographical strategy.
  */
@@ -181,35 +336,169 @@ export interface AutobiographicalConfig {
   l2BudgetTokens?: number;
   /** Token budget for L1 summaries in select() (default: 30000) */
   l1BudgetTokens?: number;
+
+  /**
+   * When true (default), each selected summary emits as its own positioned
+   * Q/A recall pair, sorted chronologically by source range. When false,
+   * all selected summaries are concatenated into one Q/A pair between head
+   * and tail (legacy behavior pre-2026-05-10).
+   *
+   * Per-region positioning is the spec-faithful behavior: it lets the agent
+   * see each memory in its temporal place rather than as a wall of unrelated
+   * recollections from another speaker. Without it, hierarchical compression
+   * is structurally similar to the dual-recall corruption pattern that
+   * caused Lena's context degradation on Hermes.
+   */
+  positionedRecallPairs?: boolean;
+
+  /**
+   * Template for the per-pair recall question header. Substitutions:
+   *   {id}    — summary id (e.g. "L1-3")
+   *   {level} — summary level (1, 2, or 3)
+   *   {first} — first source message id
+   *   {last}  — last source message id
+   * Default: '[Recall {id}]'.
+   *
+   * Only used when `positionedRecallPairs` is true.
+   */
+  recallHeaderTemplate?: string;
+
+  /**
+   * Per-tool retention limit: keep at most the last N `tool_result` blocks
+   * for each tool name. Older results get their content replaced with a
+   * brief marker referencing the tool name and how many newer results exist.
+   *
+   * Two shapes accepted:
+   *  - `number`: applies as a global default across all tools.
+   *  - `Record<toolName, number>`: per-tool limit; tools not listed are
+   *    unlimited.
+   *
+   * Default: undefined (no pruning). Use a small number (1–5) for tools
+   * that produce verbose, mostly-stale output (e.g. file listings, http
+   * fetches, log queries).
+   */
+  toolResultMaxLastN?: number | Record<string, number>;
+
+  /**
+   * Truncate `tool_use` block inputs whose serialized JSON exceeds this
+   * many tokens. The truncated input becomes `{ "_truncated": true,
+   * "_originalTokens": N }` plus a head slice of the original input
+   * keys for context. Default: 0 (no truncation).
+   */
+  toolUseInputMaxTokens?: number;
+
+  /**
+   * Cap on the number of speculative L1 summaries the strategy will hold
+   * (queued + unmerged). When `count(unmerged L1s) + count(queued chunks)`
+   * exceeds this cap, `onNewMessage`'s auto-tick is held back. Chunks
+   * still form and queue, but compression is deferred until a manual
+   * `tick()` or `compile()` triggers it.
+   *
+   * Default: undefined (no cap; compression fires eagerly on every
+   * new message when `autoTickOnNewMessage` is true).
+   */
+  maxSpeculativeL1s?: number;
+
+  /**
+   * When false, the rendering pipeline emits the full ideal context (head
+   * window + all selected summaries + all recent messages) without
+   * truncating to fit `budget.maxTokens`. The caller's API will reject if
+   * the result exceeds the model's context window — the philosophy is
+   * "surface the overage rather than silently lose content."
+   *
+   * Default: true (legacy budget-aware truncation: stops emitting recall
+   * pairs and recent messages when the running total exceeds maxTokens).
+   *
+   * Recommended setting for long-lived agents on large-context models
+   * (e.g. opus-4-7 with 1M context): false. The window is generous enough
+   * that overflow is rare, and when it does happen you want to know.
+   */
+  enforceBudget?: boolean;
+
+  // --- Adaptive resolution (per docs/adaptive-resolution-design.md) ---
+
+  /**
+   * Enable picker-driven adaptive resolution. When true, `select()` uses
+   * the FoldingStrategy + Picker to choose per-message resolution under
+   * token-budget pressure rather than the threshold-driven `checkMergeThreshold`
+   * path. Default: false (existing hierarchical behavior preserved).
+   */
+  adaptiveResolution?: boolean;
+
+  /**
+   * Folding strategy name when adaptiveResolution is on. One of:
+   *   'flat-profile' (default) — level-equalizing
+   *   'oldest-first' — chronological
+   * Custom strategies can be plugged in by the host application.
+   */
+  foldingStrategy?: 'flat-profile' | 'oldest-first';
+
+  /**
+   * Slack ratio (hysteresis) for the picker. The picker folds until total
+   * tokens ≤ budget * (1 - slack), and stays quiet while between slack
+   * and budget. Default 0.1.
+   */
+  compressionSlackRatio?: number;
+
+  /**
+   * Enable bottom-up speculative pre-production of higher-level summaries.
+   * When a new L_k summary is produced, if N siblings exist that would share
+   * an L_{k+1} parent, the L_{k+1} is enqueued for production immediately
+   * (no picker request needed). Default true when adaptiveResolution is on.
+   */
+  speculativeProduction?: boolean;
 }
 
 /**
  * Compression level in the hierarchical pyramid.
+ *
+ * Historically constrained to 1 | 2 | 3. As of the adaptive-resolution design
+ * (`docs/adaptive-resolution-design.md`), levels are unbounded: the picker
+ * can recursively produce L4, L5, ... as needed. The narrower literal type
+ * is kept as `LegacySummaryLevel` for code that still assumes the old shape.
+ */
+export type SummaryLevel = number;
+
+/**
+ * The narrow level type used by pre-adaptive-resolution code paths.
+ * Prefer `SummaryLevel` for new code.
  */
-export type SummaryLevel = 1 | 2 | 3;
+export type LegacySummaryLevel = 1 | 2 | 3;
 
 /**
  * A summary entry in the hierarchical memory pyramid.
  * L1: compressed from raw message chunks.
- * L2: merged from mergeThreshold L1s.
- * L3: merged from mergeThreshold L2s.
+ * L_{k>1}: merged from mergeThreshold L_{k-1}s.
  */
 export interface SummaryEntry {
   /** Unique ID (e.g., "L1-0", "L2-3") */
   id: string;
-  /** Compression level */
+  /** Compression level (1, 2, 3, ... — unbounded in the adaptive-resolution design) */
   level: SummaryLevel;
   /** The summary text */
   content: string;
-  /** Estimated token count (content.length / 4) */
+  /** Estimated token count (content.length / 4 or tokenizer-cached) */
   tokens: number;
-  /** Level of the sources: 0 = raw messages, 1 = L1s, 2 = L2s */
-  sourceLevel: 0 | 1 | 2;
-  /** IDs of source items (message IDs for L1, summary IDs for L2/L3) */
+  /**
+   * Level of the sources: 0 = raw messages, k = L_k summaries.
+   * Pre-adaptive code uses 0 | 1 | 2; new code may produce higher values.
+   */
+  sourceLevel: number;
+  /** IDs of source items (message IDs for L1, summary IDs for L_{k>1}) */
   sourceIds: string[];
   /** Range of original message IDs covered */
   sourceRange: { first: string; last: string };
-  /** If merged into a higher-level summary, that summary's ID */
+  /**
+   * The L_{level+1} summary this one is a source for, if produced.
+   * Pure archive metadata in the adaptive-resolution design — display
+   * decisions live on per-chunk `currentResolution`, not here.
+   */
+  parentId?: string;
+  /**
+   * @deprecated Renamed to `parentId` in the adaptive-resolution design.
+   * Kept for read compatibility with chronicles produced by the old
+   * threshold-driven path. New writes should set `parentId` only.
+   */
   mergedInto?: string;
   /** Creation timestamp */
   created: number;
@@ -217,6 +506,37 @@ export interface SummaryEntry {
   phaseType?: string;
 }
 
+/**
+ * Helper: read the parent pointer from a summary, accepting either the
+ * new `parentId` field or the deprecated `mergedInto` alias.
+ */
+export function getSummaryParentId(s: SummaryEntry): string | undefined {
+  return s.parentId ?? s.mergedInto;
+}
+
+/**
+ * A range of messages protected from compression. Pins keep a span of raw
+ * messages visible at their original position in the rendered context.
+ *
+ * - `kind: 'pin'` — generic protected range (any first/last span).
+ * - `kind: 'document'` — typically a single message containing a body of
+ *   information the agent wants to retain in full; semantically identical
+ *   to a single-message pin, distinguished by metadata for tooling.
+ */
+export interface ProtectedRange {
+  /** Stable id assigned at pin time. */
+  id: string;
+  /** First message id of the protected range (inclusive). */
+  firstMessageId: string;
+  /** Last message id of the protected range (inclusive). */
+  lastMessageId: string;
+  kind: 'pin' | 'document';
+  /** Optional human-readable label. */
+  name?: string;
+  /** Creation timestamp (ms since epoch). */
+  created: number;
+}
+
 /**
  * Phase type for knowledge extraction workflows.
  */
@@ -279,4 +599,6 @@ Write naturally, as recollection of what you experienced.`,
   summaryContextLabel: 'What do you remember from earlier?',
   summaryParticipant: 'Claude',
   maxMessageTokens: 0,
+  positionedRecallPairs: true,
+  recallHeaderTemplate: '[Recall {id}]',
 };