@framers/agentos 0.1.46 → 0.1.47

package/dist/memory/context/CompactionLog.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CompactionLog — Transparency audit trail for context window compaction.
+ *
+ * Every compaction event is logged with full provenance: what was compressed,
+ * the summary produced, entities preserved, content dropped, traces created.
+ * The log is queryable so agents and users can trace what happened to any
+ * piece of conversation history.
+ */
+import type { CompactionEntry, TransparencyLevel } from './types.js';
+export declare class CompactionLog {
+    private entries;
+    private readonly maxEntries;
+    private readonly level;
+    constructor(maxEntries?: number, level?: TransparencyLevel);
+    /** Record a compaction event. */
+    append(entry: CompactionEntry): void;
+    /** All entries, newest last. */
+    getAll(): readonly CompactionEntry[];
+    /** Get a single entry by ID. */
+    getById(id: string): CompactionEntry | undefined;
+    /** Find compaction entries that cover a specific turn index. */
+    findByTurn(turnIndex: number): CompactionEntry[];
+    /** Find entries that mention a specific entity. */
+    findByEntity(entity: string): CompactionEntry[];
+    /** Find entries within a time range. */
+    findByTimeRange(startMs: number, endMs: number): CompactionEntry[];
+    /** Search compaction summaries for a keyword. */
+    search(keyword: string): CompactionEntry[];
+    /** Aggregate statistics across all logged compactions. */
+    getStats(): CompactionLogStats;
+    /** Format a single entry for display in the agent's context or UI. */
+    static formatEntry(entry: CompactionEntry): string;
+    /** Format full log for display. */
+    format(): string;
+    /** Clear all entries. */
+    clear(): void;
+    get size(): number;
+}
+export interface CompactionLogStats {
+    totalCompactions: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    avgCompressionRatio: number;
+    totalTracesCreated: number;
+    totalEntitiesPreserved: number;
+    avgDurationMs: number;
+    oldestEntry: CompactionEntry | undefined;
+    newestEntry: CompactionEntry | undefined;
+}
+//# sourceMappingURL=CompactionLog.d.ts.map

package/dist/memory/context/CompactionLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompactionLog.d.ts","sourceRoot":"","sources":["../../../src/memory/context/CompactionLog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErE,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;gBAE9B,UAAU,SAAM,EAAE,KAAK,GAAE,iBAA6B;IAOlE,iCAAiC;IACjC,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAuBpC,gCAAgC;IAChC,MAAM,IAAI,SAAS,eAAe,EAAE;IAIpC,gCAAgC;IAChC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAIhD,gEAAgE;IAChE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE;IAMhD,mDAAmD;IACnD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;IAO/C,wCAAwC;IACxC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE;IAMlE,iDAAiD;IACjD,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE;IAO1C,0DAA0D;IAC1D,QAAQ,IAAI,kBAAkB;IA6C9B,sEAAsE;IACtE,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM;IAqBlD,mCAAmC;IACnC,MAAM,IAAI,MAAM;IAOhB,yBAAyB;IACzB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,eAAe,GAAG,SAAS,CAAC;IACzC,WAAW,EAAE,eAAe,GAAG,SAAS,CAAC;CAC1C"}

package/dist/memory/context/CompactionLog.js

@@ -0,0 +1,139 @@
+/**
+ * CompactionLog — Transparency audit trail for context window compaction.
+ *
+ * Every compaction event is logged with full provenance: what was compressed,
+ * the summary produced, entities preserved, content dropped, traces created.
+ * The log is queryable so agents and users can trace what happened to any
+ * piece of conversation history.
+ */
+export class CompactionLog {
+    constructor(maxEntries = 100, level = 'summary') {
+        this.entries = [];
+        this.maxEntries = maxEntries;
+        this.level = level;
+    }
+    // ── Write ──────────────────────────────────────────────────────────
+    /** Record a compaction event. */
+    append(entry) {
+        if (this.level === 'silent')
+            return;
+        // In 'summary' mode strip verbose fields to save memory.
+        const stored = this.level === 'summary'
+            ? {
+                ...entry,
+                droppedContent: [], // omit detailed dropped fragments
+                observationNotes: undefined,
+            }
+            : { ...entry };
+        this.entries.push(stored);
+        // Evict oldest if over retention limit.
+        while (this.entries.length > this.maxEntries) {
+            this.entries.shift();
+        }
+    }
+    // ── Read ───────────────────────────────────────────────────────────
+    /** All entries, newest last. */
+    getAll() {
+        return this.entries;
+    }
+    /** Get a single entry by ID. */
+    getById(id) {
+        return this.entries.find((e) => e.id === id);
+    }
+    /** Find compaction entries that cover a specific turn index. */
+    findByTurn(turnIndex) {
+        return this.entries.filter((e) => turnIndex >= e.turnRange[0] && turnIndex <= e.turnRange[1]);
+    }
+    /** Find entries that mention a specific entity. */
+    findByEntity(entity) {
+        const lower = entity.toLowerCase();
+        return this.entries.filter((e) => e.preservedEntities.some((pe) => pe.toLowerCase().includes(lower)));
+    }
+    /** Find entries within a time range. */
+    findByTimeRange(startMs, endMs) {
+        return this.entries.filter((e) => e.timestamp >= startMs && e.timestamp <= endMs);
+    }
+    /** Search compaction summaries for a keyword. */
+    search(keyword) {
+        const lower = keyword.toLowerCase();
+        return this.entries.filter((e) => e.summary.toLowerCase().includes(lower));
+    }
+    // ── Stats ──────────────────────────────────────────────────────────
+    /** Aggregate statistics across all logged compactions. */
+    getStats() {
+        if (this.entries.length === 0) {
+            return {
+                totalCompactions: 0,
+                totalInputTokens: 0,
+                totalOutputTokens: 0,
+                avgCompressionRatio: 0,
+                totalTracesCreated: 0,
+                totalEntitiesPreserved: 0,
+                avgDurationMs: 0,
+                oldestEntry: undefined,
+                newestEntry: undefined,
+            };
+        }
+        let totalInput = 0;
+        let totalOutput = 0;
+        let totalTraces = 0;
+        let totalDuration = 0;
+        const entitySet = new Set();
+        for (const e of this.entries) {
+            totalInput += e.inputTokens;
+            totalOutput += e.outputTokens;
+            totalTraces += e.tracesCreated.length;
+            totalDuration += e.durationMs;
+            for (const ent of e.preservedEntities)
+                entitySet.add(ent);
+        }
+        return {
+            totalCompactions: this.entries.length,
+            totalInputTokens: totalInput,
+            totalOutputTokens: totalOutput,
+            avgCompressionRatio: totalOutput > 0 ? Math.round((totalInput / totalOutput) * 10) / 10 : 0,
+            totalTracesCreated: totalTraces,
+            totalEntitiesPreserved: entitySet.size,
+            avgDurationMs: Math.round(totalDuration / this.entries.length),
+            oldestEntry: this.entries[0],
+            newestEntry: this.entries[this.entries.length - 1],
+        };
+    }
+    // ── Formatting ─────────────────────────────────────────────────────
+    /** Format a single entry for display in the agent's context or UI. */
+    static formatEntry(entry) {
+        const lines = [
+            `[Compaction ${entry.id}]`,
+            `  Time: ${new Date(entry.timestamp).toISOString()}`,
+            `  Turns: ${entry.turnRange[0]}–${entry.turnRange[1]}`,
+            `  Strategy: ${entry.strategy}`,
+            `  Compression: ${entry.inputTokens} → ${entry.outputTokens} tokens (${entry.compressionRatio.toFixed(1)}x)`,
+            `  Duration: ${entry.durationMs}ms`,
+        ];
+        if (entry.preservedEntities.length > 0) {
+            lines.push(`  Entities preserved: ${entry.preservedEntities.join(', ')}`);
+        }
+        if (entry.tracesCreated.length > 0) {
+            lines.push(`  Memory traces created: ${entry.tracesCreated.length}`);
+        }
+        if (entry.droppedContent.length > 0) {
+            lines.push(`  Dropped fragments: ${entry.droppedContent.length}`);
+        }
+        return lines.join('\n');
+    }
+    /** Format full log for display. */
+    format() {
+        if (this.entries.length === 0)
+            return '[No compaction events recorded]';
+        return this.entries.map(CompactionLog.formatEntry).join('\n\n');
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    /** Clear all entries. */
+    clear() {
+        this.entries = [];
+    }
+    get size() {
+        return this.entries.length;
+    }
+}
+//# sourceMappingURL=CompactionLog.js.map

package/dist/memory/context/CompactionLog.js.map

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

package/dist/memory/context/ContextWindowManager.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ContextWindowManager — Lifecycle orchestrator for infinite context conversations.
+ *
+ * Sits between the conversation loop and the LLM call. Before each turn:
+ * 1. Tracks all messages and their token costs
+ * 2. Checks if context window is approaching capacity
+ * 3. Triggers compaction when threshold is reached
+ * 4. Replaces old messages with compressed summaries
+ * 5. Logs every compaction with full transparency
+ * 6. Encodes important content as long-term memory traces
+ *
+ * The manager maintains a rolling summary chain so the agent always has
+ * narrative context from the full conversation history.
+ */
+import type { EmotionalContext, MemoryTrace } from '../types.js';
+import { CompactionEngine } from './CompactionEngine.js';
+import { CompactionLog, type CompactionLogStats } from './CompactionLog.js';
+import type { CompactionEntry, ContextMessage, InfiniteContextConfig, SummaryChainNode } from './types.js';
+import type { MemoryObserver } from '../observation/MemoryObserver.js';
+import type { MemoryReflector } from '../observation/MemoryReflector.js';
+export interface ContextWindowManagerConfig {
+    /** Maximum context window size in tokens. */
+    maxContextTokens: number;
+    /** Infinite context configuration. */
+    infiniteContext: Partial<InfiniteContextConfig>;
+    /** LLM invoker for summarization. */
+    llmInvoker: (prompt: string) => Promise<string>;
+    /** Optional: MemoryObserver for hybrid strategy. */
+    observer?: MemoryObserver;
+    /** Optional: MemoryReflector for hybrid strategy. */
+    reflector?: MemoryReflector;
+    /** Callback to encode traces into long-term memory. */
+    onTracesCreated?: (traces: Partial<MemoryTrace>[]) => Promise<void>;
+}
+export declare class ContextWindowManager {
+    private messages;
+    private turnCounter;
+    private readonly config;
+    private readonly maxContextTokens;
+    private readonly engine;
+    private readonly log;
+    private readonly chain;
+    private readonly onTracesCreated?;
+    /** Total compactions performed in this session. */
+    private compactionCount;
+    /** Whether a compaction is currently running (prevent re-entry). */
+    private compacting;
+    constructor(managerConfig: ContextWindowManagerConfig);
+    /**
+     * Add a message to the tracked conversation.
+     * Call this for every message (user, assistant, system, tool).
+     */
+    addMessage(role: 'user' | 'assistant' | 'system' | 'tool', content: string): void;
+    /**
+     * Check whether compaction is needed and perform it if so.
+     * Call this BEFORE assembling the prompt for the LLM.
+     *
+     * Returns the current message list (potentially compacted).
+     */
+    beforeTurn(systemPromptTokens: number, memoryBudgetTokens: number, emotionalContext?: EmotionalContext): Promise<ContextMessage[]>;
+    /**
+     * Get the formatted summary chain for injection into the system prompt
+     * or as a conversation-history block.
+     */
+    getSummaryContext(): string;
+    /** Get all current messages (including any summary blocks). */
+    getMessages(): readonly ContextMessage[];
+    /** Get only the raw (non-compacted) messages. */
+    getRawMessages(): ContextMessage[];
+    /** Current total token estimate across all messages. */
+    getCurrentTokens(): number;
+    /** Current turn index. */
+    getCurrentTurn(): number;
+    /** Replace the message list (e.g. after external manipulation). */
+    setMessages(messages: ContextMessage[]): void;
+    /** Get the compaction log. */
+    getLog(): CompactionLog;
+    /** Get all compaction entries. */
+    getCompactionHistory(): readonly CompactionEntry[];
+    /** Get aggregate stats. */
+    getStats(): ContextWindowStats;
+    /** Get the summary chain for UI display. */
+    getSummaryChain(): SummaryChainNode[];
+    /** Search the compaction log for a keyword. */
+    searchHistory(keyword: string): CompactionEntry[];
+    /** Find what happened to a specific turn. */
+    findTurnHistory(turnIndex: number): CompactionEntry[];
+    /**
+     * Format a transparency report for the agent's context.
+     * Includes: current state, recent compactions, summary chain.
+     */
+    formatTransparencyReport(): string;
+    /** Reset all state. */
+    clear(): void;
+    /** Get the compaction engine (for strategy inspection/testing). */
+    getEngine(): CompactionEngine;
+    /** Whether infinite context is enabled. */
+    get enabled(): boolean;
+    /** Current config (read-only). */
+    getConfig(): Readonly<InfiniteContextConfig>;
+}
+export interface ContextWindowStats extends CompactionLogStats {
+    currentTokens: number;
+    maxTokens: number;
+    utilization: number;
+    currentTurn: number;
+    messageCount: number;
+    compactedMessageCount: number;
+    summaryChainNodes: number;
+    summaryChainTokens: number;
+    strategy: string;
+    enabled: boolean;
+}
+//# sourceMappingURL=ContextWindowManager.d.ts.map

package/dist/memory/context/ContextWindowManager.d.ts.map

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

package/dist/memory/context/ContextWindowManager.js

@@ -0,0 +1,225 @@
+/**
+ * ContextWindowManager — Lifecycle orchestrator for infinite context conversations.
+ *
+ * Sits between the conversation loop and the LLM call. Before each turn:
+ * 1. Tracks all messages and their token costs
+ * 2. Checks if context window is approaching capacity
+ * 3. Triggers compaction when threshold is reached
+ * 4. Replaces old messages with compressed summaries
+ * 5. Logs every compaction with full transparency
+ * 6. Encodes important content as long-term memory traces
+ *
+ * The manager maintains a rolling summary chain so the agent always has
+ * narrative context from the full conversation history.
+ */
+import { CompactionEngine } from './CompactionEngine.js';
+import { CompactionLog } from './CompactionLog.js';
+import { RollingSummaryChain } from './RollingSummaryChain.js';
+import { DEFAULT_INFINITE_CONTEXT_CONFIG } from './types.js';
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export class ContextWindowManager {
+    constructor(managerConfig) {
+        this.messages = [];
+        this.turnCounter = 0;
+        /** Total compactions performed in this session. */
+        this.compactionCount = 0;
+        /** Whether a compaction is currently running (prevent re-entry). */
+        this.compacting = false;
+        this.config = {
+            ...DEFAULT_INFINITE_CONTEXT_CONFIG,
+            ...managerConfig.infiniteContext,
+        };
+        this.maxContextTokens = managerConfig.maxContextTokens;
+        this.onTracesCreated = managerConfig.onTracesCreated;
+        const llmInvoker = this.config.llmInvoker ?? managerConfig.llmInvoker;
+        this.engine = new CompactionEngine(llmInvoker, managerConfig.observer, managerConfig.reflector);
+        this.log = new CompactionLog(this.config.logRetention, this.config.transparencyLevel);
+        this.chain = new RollingSummaryChain(this.config.maxSummaryChainTokens, llmInvoker);
+    }
+    // ── Core API ───────────────────────────────────────────────────────
+    /**
+     * Add a message to the tracked conversation.
+     * Call this for every message (user, assistant, system, tool).
+     */
+    addMessage(role, content) {
+        const msg = {
+            role,
+            content,
+            timestamp: Date.now(),
+            turnIndex: this.turnCounter,
+            tokenEstimate: estimateTokens(content),
+        };
+        this.messages.push(msg);
+        // Increment turn counter on user messages (start of a new turn).
+        if (role === 'user') {
+            this.turnCounter++;
+        }
+    }
+    /**
+     * Check whether compaction is needed and perform it if so.
+     * Call this BEFORE assembling the prompt for the LLM.
+     *
+     * Returns the current message list (potentially compacted).
+     */
+    async beforeTurn(systemPromptTokens, memoryBudgetTokens, emotionalContext) {
+        if (!this.config.enabled || this.compacting) {
+            return this.messages;
+        }
+        const conversationTokens = this.messages.reduce((s, m) => s + m.tokenEstimate, 0);
+        const totalTokens = systemPromptTokens + memoryBudgetTokens + conversationTokens;
+        const threshold = this.maxContextTokens * this.config.compactionThreshold;
+        if (totalTokens < threshold) {
+            return this.messages;
+        }
+        // Perform compaction.
+        this.compacting = true;
+        try {
+            const result = await this.engine.compact({
+                messages: this.messages,
+                maxContextTokens: this.maxContextTokens,
+                currentTokens: totalTokens,
+                summaryChain: this.chain.getAllNodes(),
+                emotionalContext,
+            }, this.config);
+            // Update internal state.
+            this.messages = result.messages;
+            this.chain.addNodes(result.newNodes);
+            this.log.append(result.entry);
+            this.compactionCount++;
+            // Collapse the summary chain if it's grown too large.
+            const collapseNodes = await this.chain.collapse();
+            if (collapseNodes.length > 0) {
+                this.chain.addNodes(collapseNodes);
+            }
+            // Encode any traces produced by the compaction (hybrid strategy).
+            if (result.tracesToEncode.length > 0 && this.onTracesCreated) {
+                // Fire and forget — don't block the conversation turn.
+                this.onTracesCreated(result.tracesToEncode).catch(() => {
+                    /* trace encoding failure is non-fatal */
+                });
+            }
+            return this.messages;
+        }
+        finally {
+            this.compacting = false;
+        }
+    }
+    /**
+     * Get the formatted summary chain for injection into the system prompt
+     * or as a conversation-history block.
+     */
+    getSummaryContext() {
+        return this.chain.formatForPrompt();
+    }
+    // ── Message Management ─────────────────────────────────────────────
+    /** Get all current messages (including any summary blocks). */
+    getMessages() {
+        return this.messages;
+    }
+    /** Get only the raw (non-compacted) messages. */
+    getRawMessages() {
+        return this.messages.filter((m) => !m.compacted);
+    }
+    /** Current total token estimate across all messages. */
+    getCurrentTokens() {
+        return this.messages.reduce((s, m) => s + m.tokenEstimate, 0);
+    }
+    /** Current turn index. */
+    getCurrentTurn() {
+        return this.turnCounter;
+    }
+    /** Replace the message list (e.g. after external manipulation). */
+    setMessages(messages) {
+        this.messages = messages;
+    }
+    // ── Transparency ───────────────────────────────────────────────────
+    /** Get the compaction log. */
+    getLog() {
+        return this.log;
+    }
+    /** Get all compaction entries. */
+    getCompactionHistory() {
+        return this.log.getAll();
+    }
+    /** Get aggregate stats. */
+    getStats() {
+        const logStats = this.log.getStats();
+        return {
+            ...logStats,
+            currentTokens: this.getCurrentTokens(),
+            maxTokens: this.maxContextTokens,
+            utilization: this.getCurrentTokens() / this.maxContextTokens,
+            currentTurn: this.turnCounter,
+            messageCount: this.messages.length,
+            compactedMessageCount: this.messages.filter((m) => m.compacted).length,
+            summaryChainNodes: this.chain.size,
+            summaryChainTokens: this.chain.getTotalTokens(),
+            strategy: this.config.strategy,
+            enabled: this.config.enabled,
+        };
+    }
+    /** Get the summary chain for UI display. */
+    getSummaryChain() {
+        return this.chain.getAllNodes();
+    }
+    /** Search the compaction log for a keyword. */
+    searchHistory(keyword) {
+        return this.log.search(keyword);
+    }
+    /** Find what happened to a specific turn. */
+    findTurnHistory(turnIndex) {
+        return this.log.findByTurn(turnIndex);
+    }
+    /**
+     * Format a transparency report for the agent's context.
+     * Includes: current state, recent compactions, summary chain.
+     */
+    formatTransparencyReport() {
+        const stats = this.getStats();
+        const lines = [
+            '=== Context Window Status ===',
+            `Tokens: ${stats.currentTokens}/${stats.maxTokens} (${(stats.utilization * 100).toFixed(1)}%)`,
+            `Turn: ${stats.currentTurn}, Messages: ${stats.messageCount} (${stats.compactedMessageCount} compacted)`,
+            `Strategy: ${stats.strategy}, Compactions: ${stats.totalCompactions}`,
+        ];
+        if (stats.totalCompactions > 0) {
+            lines.push(`Avg compression: ${stats.avgCompressionRatio}x, Total traces created: ${stats.totalTracesCreated}`);
+        }
+        const recent = this.log.getAll().slice(-3);
+        if (recent.length > 0) {
+            lines.push('', '--- Recent Compactions ---');
+            for (const entry of recent) {
+                lines.push(CompactionLog.formatEntry(entry));
+            }
+        }
+        const summaryContext = this.chain.formatForPrompt();
+        if (summaryContext) {
+            lines.push('', '--- Summary Chain ---', summaryContext);
+        }
+        return lines.join('\n');
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    /** Reset all state. */
+    clear() {
+        this.messages = [];
+        this.turnCounter = 0;
+        this.compactionCount = 0;
+        this.log.clear();
+        this.chain.clear();
+    }
+    /** Get the compaction engine (for strategy inspection/testing). */
+    getEngine() {
+        return this.engine;
+    }
+    /** Whether infinite context is enabled. */
+    get enabled() {
+        return this.config.enabled;
+    }
+    /** Current config (read-only). */
+    getConfig() {
+        return this.config;
+    }
+}
+//# sourceMappingURL=ContextWindowManager.js.map

package/dist/memory/context/ContextWindowManager.js.map

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

package/dist/memory/context/RollingSummaryChain.d.ts

@@ -0,0 +1,53 @@
+/**
+ * RollingSummaryChain — Linked chain of conversation summaries.
+ *
+ * Each compaction produces a summary node. When the chain itself exceeds
+ * its token budget, older nodes are re-summarized into higher-level nodes
+ * (summary-of-summaries), forming a tree structure:
+ *
+ *   [L2: turns 1-300]
+ *     ├── [L1: turns 1-120]
+ *     │     ├── [L0: turns 1-50]
+ *     │     └── [L0: turns 51-120]
+ *     └── [L1: turns 121-300]
+ *           ├── [L0: turns 121-200]
+ *           └── [L0: turns 201-300]
+ *
+ * The chain head (highest-level summary covering all compacted turns)
+ * is always included in the prompt as "conversation so far".
+ */
+import type { SummaryChainNode } from './types.js';
+export declare class RollingSummaryChain {
+    private nodes;
+    private readonly maxBudgetTokens;
+    private readonly llmInvoker?;
+    constructor(maxBudgetTokens?: number, llmInvoker?: (prompt: string) => Promise<string>);
+    /** Add new leaf nodes from a compaction. */
+    addNodes(nodes: SummaryChainNode[]): void;
+    /**
+     * Collapse the chain if it exceeds the token budget.
+     * Merges the oldest leaf nodes into a higher-level summary.
+     * Returns any newly created parent nodes.
+     */
+    collapse(): Promise<SummaryChainNode[]>;
+    /** Get the active chain — top-level nodes without parents, sorted by turn range. */
+    getActiveChain(): SummaryChainNode[];
+    /** Format the chain for inclusion in a prompt. */
+    formatForPrompt(): string;
+    /** Total tokens across all active (non-absorbed) nodes. */
+    getTotalTokens(): number;
+    /** Get all nodes (including absorbed children, for audit/UI). */
+    getAllNodes(): SummaryChainNode[];
+    /** Get the full turn range covered by the chain. */
+    getCoveredRange(): [number, number] | null;
+    get size(): number;
+    /** Active leaves = nodes without a parent, sorted by turn range. */
+    private getActiveLeaves;
+    /** Merge multiple nodes into a single higher-level summary. */
+    private mergeNodes;
+    /** Non-LLM fallback: concatenate and truncate to budget. */
+    private fallbackMerge;
+    /** Reset the chain. */
+    clear(): void;
+}
+//# sourceMappingURL=RollingSummaryChain.d.ts.map

package/dist/memory/context/RollingSummaryChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RollingSummaryChain.d.ts","sourceRoot":"","sources":["../../../src/memory/context/RollingSummaryChain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAOnD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAsC;gBAGhE,eAAe,SAAO,EACtB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC;IAQlD,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAMzC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA4B7C,oFAAoF;IACpF,cAAc,IAAI,gBAAgB,EAAE;IAIpC,kDAAkD;IAClD,eAAe,IAAI,MAAM;IAuBzB,2DAA2D;IAC3D,cAAc,IAAI,MAAM;IAOxB,iEAAiE;IACjE,WAAW,IAAI,gBAAgB,EAAE;IAMjC,oDAAoD;IACpD,eAAe,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAM1C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID,oEAAoE;IACpE,OAAO,CAAC,eAAe;IAMvB,+DAA+D;YACjD,UAAU;IAkDxB,4DAA4D;IAC5D,OAAO,CAAC,aAAa;IA8BrB,uBAAuB;IACvB,KAAK,IAAI,IAAI;CAGd"}