@animalabs/context-manager 0.1.0

package/dist/src/strategies/autobiographical.d.ts

@@ -0,0 +1,199 @@
+import type { ContentBlock } from '@animalabs/membrane';
+import { NativeFormatter } from '@animalabs/membrane';
+import type { ResettableStrategy, StrategyContext, ReadinessState, MessageStoreView, ContextLogView, TokenBudget, ContextEntry, StoredMessage, AutobiographicalConfig, SummaryLevel, SummaryEntry } from '../types/index.js';
+/**
+ * Chunk of messages to be compressed.
+ */
+export interface Chunk {
+    /** Index in the chunk list */
+    index: number;
+    /** Starting index in the compressible message array (inclusive).
+     *  Note: this is an index into getCompressibleMessages(), not store.getAll(). */
+    startIndex: number;
+    /** Ending index in the compressible message array (exclusive).
+     *  Note: this is an index into getCompressibleMessages(), not store.getAll(). */
+    endIndex: number;
+    /** Messages in this chunk */
+    messages: StoredMessage[];
+    /** Estimated token count */
+    tokens: number;
+    /** Whether this chunk has been compressed */
+    compressed: boolean;
+    /** The diary entry if compressed (legacy mode) */
+    diary?: string;
+    /** ID of the L1 SummaryEntry (hierarchical mode) */
+    summaryId?: string;
+    /** Phase type tag (set by KnowledgeStrategy for semantic chunking) */
+    phaseType?: string;
+}
+/**
+ * Autobiographical chunking strategy.
+ * Compresses old conversation chunks into summaries in the model's own words.
+ * Recent context stays untouched.
+ *
+ * When `hierarchical` is enabled, uses a 3-level compression pyramid:
+ * L1 (raw→summary) → L2 (merge N L1s) → L3 (merge N L2s)
+ * with anti-redundancy filtering and budget carryover.
+ */
+export declare class AutobiographicalStrategy implements ResettableStrategy {
+    readonly name: string;
+    get maxMessageTokens(): number;
+    protected config: AutobiographicalConfig;
+    protected chunks: Chunk[];
+    protected pendingCompression: Promise<void> | null;
+    protected compressionQueue: number[];
+    protected _compressionCount: number;
+    protected summaries: SummaryEntry[];
+    protected summaryIdCounter: number;
+    protected mergeQueue: Array<{
+        level: SummaryLevel;
+        sourceIds: string[];
+    }>;
+    protected nativeFormatter: NativeFormatter;
+    /** Message ID from which the head window starts. null = start from message 0. */
+    protected headWindowStartId: string | null;
+    /** Cached result of getHeadWindowStartIndex to avoid repeated linear scans. */
+    private _cachedHeadStartIndex;
+    constructor(config?: Partial<AutobiographicalConfig>);
+    initialize(ctx: StrategyContext): Promise<void>;
+    checkReadiness(): ReadinessState;
+    onNewMessage(message: StoredMessage, ctx: StrategyContext): Promise<void>;
+    tick(ctx: StrategyContext): Promise<void>;
+    select(store: MessageStoreView, log: ContextLogView, budget: TokenBudget): ContextEntry[];
+    /**
+     * Get summary statistics for observability.
+     */
+    getStats(): {
+        chunksTotal: number;
+        chunksCompressed: number;
+        compressionCount: number;
+        l1: number;
+        l2: number;
+        l3: number;
+        pendingMerges: number;
+    };
+    protected selectLegacy(store: MessageStoreView, _log: ContextLogView, budget: TokenBudget): ContextEntry[];
+    protected compressChunkLegacy(chunk: Chunk, ctx: StrategyContext): Promise<void>;
+    protected buildPriorContextLegacy(chunk: Chunk, ctx: StrategyContext): Array<{
+        participant: string;
+        content: ContentBlock[];
+    }>;
+    /**
+     * Anti-redundancy filter: get summaries to show, excluding those whose
+     * children are all already visible at a lower level.
+     *
+     * Matches moltbot's gradient exclusion algorithm (worker.ts:293-447).
+     */
+    protected getAntiRedundantSummaries(excludeMessageIds?: Set<string>): {
+        shownL1: SummaryEntry[];
+        shownL2: SummaryEntry[];
+        shownL3: SummaryEntry[];
+    };
+    /**
+     * Compress a raw message chunk into an L1 summary using self-voice framing.
+     * No system prompt — framing via message structure only.
+     */
+    protected compressChunkHierarchical(chunk: Chunk, ctx: StrategyContext): Promise<void>;
+    /**
+     * Check if unmerged summary counts exceed the merge threshold.
+     * Enqueues merge operations if so.
+     */
+    protected checkMergeThreshold(): void;
+    /**
+     * Merge N summaries at one level into a single summary at the next level.
+     * Uses self-voice consolidation prompt.
+     */
+    protected executeMerge(targetLevel: SummaryLevel, sourceIds: string[], ctx: StrategyContext): Promise<void>;
+    /**
+     * Select context entries using hierarchical compression with budget carryover.
+     * Matches moltbot's budget waterfall: L3 → L2 → L1 with unused budget flowing down.
+     */
+    protected selectHierarchical(store: MessageStoreView, budget: TokenBudget): ContextEntry[];
+    /**
+     * Build the compression instruction for an L1 chunk.
+     * Override in subclasses for phase-aware prompts.
+     */
+    protected getCompressionInstruction(chunk: Chunk, targetTokens: number): string;
+    /**
+     * Build the merge instruction for combining summaries into a higher level.
+     * Override in subclasses for domain-specific merge prompts.
+     */
+    protected getMergeInstruction(targetLevel: SummaryLevel, sources: SummaryEntry[], targetTokens: number): string;
+    /**
+     * Select L1 summaries within a budget. Returns selected summaries and tokens used.
+     * Override in subclasses for asymmetric budget allocation (e.g., cap research, prioritize synthesis).
+     */
+    protected selectL1Summaries(shownL1: SummaryEntry[], budget: number, maxTokens: number): {
+        selected: SummaryEntry[];
+        tokensUsed: number;
+    };
+    /**
+     * Reset the head window to start from a new message ID.
+     * Old head window messages become compressible on the next chunk rebuild.
+     */
+    resetHeadWindow(newStartId: string | null): void;
+    /**
+     * Generate a transition summary from the current head window + top summaries.
+     * Used when `/newtopic` is called without explicit context.
+     */
+    generateTransitionSummary(ctx: StrategyContext): Promise<string>;
+    /**
+     * Check if a message is a topic transition marker.
+     */
+    protected isTopicTransitionMessage(message: StoredMessage): boolean;
+    /**
+     * Extract plain text from content blocks.
+     */
+    protected extractText(content: ContentBlock[]): string;
+    /**
+     * Get messages in the compressible zone: outside both head window and recent window.
+     * Returns messages from [0, headStart) ∪ [headEnd, recentStart).
+     */
+    protected getCompressibleMessages(store: MessageStoreView): StoredMessage[];
+    /**
+     * Rebuild chunk boundaries based on current messages.
+     */
+    protected rebuildChunks(store: MessageStoreView): void;
+    protected createChunk(index: number, startIndex: number, endIndex: number, messages: StoredMessage[], tokens: number, existingCompressed: Map<string, Chunk>): Chunk;
+    protected chunkKey(chunk: Chunk): string;
+    protected getRecentWindowStart(store: MessageStoreView): number;
+    /**
+     * Index of the first message in the head window.
+     * When headWindowStartId is set, the head window starts from that message
+     * instead of message 0 — old messages before it become compressible.
+     */
+    protected getHeadWindowStartIndex(store: MessageStoreView): number;
+    /**
+     * Index of the first message AFTER the head window.
+     * Messages [headStart, headEnd) are preserved verbatim.
+     */
+    protected getHeadWindowEnd(store: MessageStoreView): number;
+    protected hasToolUse(message: StoredMessage): boolean;
+    protected hasToolResult(message: StoredMessage): boolean;
+    /**
+     * Remove trailing entries that contain tool_use without a following tool_result.
+     * This prevents orphaned tool_use blocks when a budget break cuts between
+     * a tool_use message and its tool_result response.
+     */
+    private trimOrphanedToolUse;
+    protected isChunkOldEnough(chunk: Chunk): boolean;
+    protected formatChunkForCompression(chunk: Chunk): string;
+    /**
+     * Collapse consecutive messages from the same participant into single messages.
+     * Required because Claude API rejects consecutive same-role messages.
+     */
+    protected collapseConsecutiveMessages(messages: Array<{
+        participant: string;
+        content: ContentBlock[];
+    }>): Array<{
+        participant: string;
+        content: ContentBlock[];
+    }>;
+    protected estimateTextOnlyTokens(msg: StoredMessage): number;
+    protected estimateTokens(content: ContentBlock[]): number;
+    /**
+     * Truncate a message's content blocks to fit within maxMessageTokens.
+     */
+    protected truncateContent(content: ContentBlock[], maxTokens: number): ContentBlock[];
+}
+//# sourceMappingURL=autobiographical.d.ts.map

package/dist/src/strategies/autobiographical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autobiographical.d.ts","sourceRoot":"","sources":["../../../src/strategies/autobiographical.ts"],"names":[],"mappings":"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"}