/** * Context Manager - Manage agent context windows * * Handles context budgeting, windowing, and optimization. */ import type { ContextBudgetResult, ContextCompactionPolicyProtocol } from './policy'; /** * Context item */ export interface ContextItem { id: string; content: string; role: 'system' | 'user' | 'assistant' | 'tool'; priority: number; tokens: number; timestamp: number; metadata?: Record; } /** * Context budget */ export interface ContextBudget { maxTokens: number; reservedTokens: number; usedTokens: number; availableTokens: number; } /** * Context Manager configuration */ export interface ContextManagerConfig { /** Maximum context tokens */ maxTokens?: number; /** Reserved tokens for response */ reservedTokens?: number; /** Token estimation ratio (chars per token) */ tokenRatio?: number; /** Priority threshold for eviction */ evictionThreshold?: number; /** * Compaction policy (see context/policy.ts; Python parity with * `ContextCompactionPolicy` in praisonaiagents/context/policy.py). * When given, its `triggerAt` becomes the manager's compaction * threshold, `targetUtilization` the post-compaction target, * `preserveLastNTurns` the number of recent non-system items that are * never compacted, and `strategy` decides what is dropped first. */ policy?: ContextCompactionPolicyProtocol | null; /** * Fraction (0-1) of the usable budget (maxTokens - reservedTokens) at * which `add()` compacts. Defaults to `policy.triggerAt` when a policy * is given; with neither, policy-driven compaction is off and only the * hard limit is enforced (the pre-policy behaviour). */ compactThreshold?: number; } /** * ContextManager - Manage context windows for agents */ export declare class ContextManager { readonly id: string; private items; private maxTokens; private reservedTokens; private tokenRatio; private evictionThreshold; private policy; private compactThreshold; constructor(config?: ContextManagerConfig); /** * The compaction policy driving this manager, if any. */ getPolicy(): ContextCompactionPolicyProtocol | null; /** * Fraction of the usable budget at which `add()` compacts, or null when * policy-driven compaction is disabled. */ getCompactThreshold(): number | null; /** * Current utilization: used tokens over the usable budget * (maxTokens - reservedTokens). 1.0 when there is no usable budget. */ getUtilization(): number; /** * Whether the policy (or explicit compactThreshold) says the context * should be compacted now. */ shouldCompact(): boolean; /** * Run the policy's budget analysis over the current items, using the * model's context window rather than this manager's maxTokens. * Returns null when no policy is configured. */ evaluateBudget(model?: string): ContextBudgetResult | null; /** * Compact the context according to the policy until utilization is at or * below the policy's `targetUtilization` (or the compactThreshold when * there is no policy). * * System items and the most recent `preserveLastNTurns` non-system items * are never removed. With `drop_oldest_tools`, tool items are dropped * oldest-first before anything else; the other strategies drop the * oldest non-system items (`summarise` has no summarizer here, so it * falls back to dropping oldest -- pass a summarizer to `compress()` for * LLM-backed summaries). * * @returns Number of tokens removed. */ compact(): number; /** * Add item to context */ add(content: string, role: ContextItem['role'], options?: { priority?: number; metadata?: any; }): ContextItem; /** * Add system message */ addSystem(content: string, priority?: number): ContextItem; /** * Add user message */ addUser(content: string, priority?: number): ContextItem; /** * Add assistant message */ addAssistant(content: string, priority?: number): ContextItem; /** * Add tool result */ addTool(content: string, priority?: number): ContextItem; /** * Get all items */ getAll(): ContextItem[]; /** * Get items by role */ getByRole(role: ContextItem['role']): ContextItem[]; /** * Get budget info */ getBudget(): ContextBudget; /** * Build context string */ build(): string; /** * Build as messages array */ buildMessages(): Array<{ role: string; content: string; }>; /** * Clear context */ clear(): void; /** * Remove item by ID */ remove(id: string): boolean; /** * Compress context by summarizing old items */ compress(summarizer?: (items: ContextItem[]) => Promise): void; /** * Estimate tokens for text */ estimateTokens(text: string): number; /** * Enforce token limit */ private enforceLimit; /** * Get stats */ getStats(): { itemCount: number; totalTokens: number; byRole: Record; oldestTimestamp: number; newestTimestamp: number; }; } /** * Create context manager */ export declare function createContextManager(config?: ContextManagerConfig): ContextManager; export default ContextManager;