@compilr-dev/agents 0.0.1

package/dist/anchors/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Anchors - Critical information that survives context compaction
+ *
+ * Anchors are pieces of information that:
+ * 1. Never get compacted - Survive all context management
+ * 2. Always re-injected - Present in every LLM call
+ * 3. Scoped - Session, persistent, or temporary
+ * 4. Prioritized - Critical, safety, or informational
+ */
+/**
+ * Priority levels for anchors
+ * - critical: Must remember, highest priority (e.g., "we just implemented X")
+ * - safety: Check before acting (e.g., "verify before git reset")
+ * - info: Useful context (e.g., "modified files this session")
+ */
+export type AnchorPriority = 'critical' | 'safety' | 'info';
+/**
+ * Scope determines anchor lifetime
+ * - session: Lives for the current session only
+ * - persistent: Saved to disk, survives across sessions
+ * - temporary: Auto-expires after a duration or event
+ */
+export type AnchorScope = 'session' | 'persistent' | 'temporary';
+/**
+ * An anchor - critical information that survives context compaction
+ */
+export interface Anchor {
+    /**
+     * Unique identifier for this anchor
+     */
+    id: string;
+    /**
+     * The content to remember (injected into every LLM call)
+     */
+    content: string;
+    /**
+     * Priority level determines display order and emphasis
+     */
+    priority: AnchorPriority;
+    /**
+     * Scope determines lifetime and persistence behavior
+     */
+    scope: AnchorScope;
+    /**
+     * When this anchor was created
+     */
+    createdAt: Date;
+    /**
+     * When this anchor expires (for temporary anchors)
+     */
+    expiresAt?: Date;
+    /**
+     * Optional tags for filtering and grouping
+     */
+    tags?: string[];
+    /**
+     * Optional metadata for custom use
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for adding a new anchor (id and createdAt are auto-generated if not provided)
+ */
+export interface AnchorInput {
+    id?: string;
+    content: string;
+    priority: AnchorPriority;
+    scope: AnchorScope;
+    expiresAt?: Date;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for querying anchors
+ */
+export interface AnchorQueryOptions {
+    /**
+     * Filter by priority level
+     */
+    priority?: AnchorPriority;
+    /**
+     * Filter by scope
+     */
+    scope?: AnchorScope;
+    /**
+     * Filter by tags (anchors must have ALL specified tags)
+     */
+    tags?: string[];
+    /**
+     * Include expired temporary anchors (default: false)
+     */
+    includeExpired?: boolean;
+}
+/**
+ * Options for clearing anchors
+ */
+export interface AnchorClearOptions {
+    /**
+     * Clear only anchors with this scope
+     */
+    scope?: AnchorScope;
+    /**
+     * Clear only anchors with these tags
+     */
+    tags?: string[];
+    /**
+     * Clear only expired anchors
+     */
+    expiredOnly?: boolean;
+}
+/**
+ * Configuration for the AnchorManager
+ */
+export interface AnchorManagerOptions {
+    /**
+     * Maximum number of anchors to keep (default: 20)
+     * When exceeded, oldest low-priority anchors are removed first
+     */
+    maxAnchors?: number;
+    /**
+     * Maximum tokens budget for anchors (default: 2000)
+     * Anchors exceeding this budget are truncated or removed
+     */
+    maxTokens?: number;
+    /**
+     * Path for persisting anchors (for scope: 'persistent')
+     * If not provided, persistent anchors work like session anchors
+     */
+    persistPath?: string;
+    /**
+     * Include built-in default safety anchors (default: true)
+     */
+    includeDefaults?: boolean;
+    /**
+     * Token estimator function (default: rough estimate based on chars)
+     */
+    estimateTokens?: (content: string) => number;
+}
+/**
+ * Serialized anchor for persistence
+ */
+export interface SerializedAnchor {
+    id: string;
+    content: string;
+    priority: AnchorPriority;
+    scope: AnchorScope;
+    createdAt: string;
+    expiresAt?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Event types for anchor operations
+ */
+export type AnchorEventType = 'anchor:added' | 'anchor:removed' | 'anchor:expired' | 'anchor:budget_exceeded' | 'anchor:persisted' | 'anchor:loaded';
+/**
+ * Anchor event payload
+ */
+export interface AnchorEvent {
+    type: AnchorEventType;
+    anchor?: Anchor;
+    anchors?: Anchor[];
+    message?: string;
+}
+/**
+ * Event handler for anchor events
+ */
+export type AnchorEventHandler = (event: AnchorEvent) => void;

package/dist/anchors/types.js

@@ -0,0 +1,10 @@
+/**
+ * Anchors - Critical information that survives context compaction
+ *
+ * Anchors are pieces of information that:
+ * 1. Never get compacted - Survive all context management
+ * 2. Always re-injected - Present in every LLM call
+ * 3. Scoped - Session, persistent, or temporary
+ * 4. Prioritized - Critical, safety, or informational
+ */
+export {};

package/dist/context/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Context Management Module
+ *
+ * Provides context window management for agents, including:
+ * - Token tracking
+ * - Filtering (truncate large content)
+ * - Compaction (save to files, replace with references)
+ * - Summarization (compress history when near limit)
+ */
+export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './manager.js';
+export type { ContextManagerOptions } from './manager.js';
+export type { ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, } from './types.js';

package/dist/context/index.js

@@ -0,0 +1,10 @@
+/**
+ * Context Management Module
+ *
+ * Provides context window management for agents, including:
+ * - Token tracking
+ * - Filtering (truncate large content)
+ * - Compaction (save to files, replace with references)
+ * - Summarization (compress history when near limit)
+ */
+export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './manager.js';

package/dist/context/manager.d.ts

@@ -0,0 +1,224 @@
+/**
+ * ContextManager - Manages agent context windows
+ *
+ * Handles token tracking, compaction, summarization, and filtering
+ * to keep agent context within limits while preserving important information.
+ *
+ * @example
+ * ```typescript
+ * const contextManager = new ContextManager({
+ *   provider,
+ *   maxContextTokens: 200000,
+ * });
+ *
+ * // Check if action needed
+ * if (contextManager.needsSummarization()) {
+ *   await contextManager.summarize(messages);
+ * }
+ * ```
+ */
+import type { Message, LLMProvider } from '../providers/types.js';
+import type { ContextConfig, ContextStats, CompactionResult, SummarizationResult, ContextEventHandler, ContextCategory, CategoryBudgetInfo, BudgetAllocation, PreflightResult, VerbosityLevel } from './types.js';
+/**
+ * Default budget allocation
+ */
+export declare const DEFAULT_BUDGET_ALLOCATION: BudgetAllocation;
+/**
+ * Default context configuration
+ */
+export declare const DEFAULT_CONTEXT_CONFIG: ContextConfig;
+/**
+ * Options for creating a ContextManager
+ */
+export interface ContextManagerOptions {
+    /**
+     * LLM provider (for token counting)
+     */
+    provider: LLMProvider;
+    /**
+     * Configuration overrides
+     */
+    config?: Partial<ContextConfig>;
+    /**
+     * Event handler for context events
+     */
+    onEvent?: ContextEventHandler;
+}
+/**
+ * ContextManager tracks and manages context window usage
+ */
+export declare class ContextManager {
+    private readonly provider;
+    private readonly config;
+    private readonly onEvent?;
+    private cachedTokenCount;
+    private turnCount;
+    private compactionCount;
+    private summarizationCount;
+    private lastCompactionTurn;
+    private categoryUsage;
+    constructor(options: ContextManagerOptions);
+    /**
+     * Merge partial config with defaults
+     */
+    private mergeConfig;
+    /**
+     * Emit a context event
+     */
+    private emit;
+    /**
+     * Count tokens in messages using the provider
+     */
+    countTokens(messages: Message[]): Promise<number>;
+    /**
+     * Update token count for messages
+     */
+    updateTokenCount(messages: Message[]): Promise<number>;
+    /**
+     * Get current token count (cached)
+     */
+    getTokenCount(): number;
+    /**
+     * Get context utilization (0.0 - 1.0)
+     */
+    getUtilization(): number;
+    /**
+     * Get maximum context tokens
+     */
+    getMaxTokens(): number;
+    /**
+     * Increment turn count (call after each assistant response)
+     */
+    incrementTurn(): void;
+    /**
+     * Check if compaction is needed
+     */
+    needsCompaction(): boolean;
+    /**
+     * Check if summarization is needed (more aggressive than compaction)
+     */
+    needsSummarization(): boolean;
+    /**
+     * Check if content should be filtered before adding
+     */
+    shouldFilter(tokenCount: number): boolean;
+    /**
+     * Get context statistics
+     */
+    getStats(messageCount: number): ContextStats;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): ContextConfig;
+    /**
+     * Get budget information for a specific category
+     */
+    getCategoryBudget(category: ContextCategory): CategoryBudgetInfo;
+    /**
+     * Get budget information for all categories
+     */
+    getAllBudgets(): Record<ContextCategory, CategoryBudgetInfo>;
+    /**
+     * Update token usage for a category
+     */
+    updateCategoryUsage(category: ContextCategory, tokens: number): void;
+    /**
+     * Add tokens to a category
+     */
+    addToCategory(category: ContextCategory, tokens: number): void;
+    /**
+     * Check if a specific category needs compaction
+     */
+    categoryNeedsCompaction(category: ContextCategory): boolean;
+    /**
+     * Compact only a specific category
+     *
+     * This is more targeted than full compaction - only affects messages
+     * in the specified category, leaving others untouched.
+     */
+    compactCategory(messages: Message[], category: ContextCategory, saveToFile: (content: string, index: number) => Promise<string>): Promise<{
+        messages: Message[];
+        result: CompactionResult;
+    }>;
+    /**
+     * Determine which category a message belongs to
+     */
+    private categorizeMessage;
+    /**
+     * Estimate tokens for a string content
+     */
+    estimateTokens(content: string): number;
+    /**
+     * Check if content can be added to a category
+     *
+     * Returns a pre-flight result with recommendations for action.
+     */
+    canAddContent(estimatedTokens: number, category: ContextCategory): PreflightResult;
+    /**
+     * Get current verbosity level based on context utilization
+     *
+     * Tools should adapt their output based on this level.
+     */
+    getVerbosityLevel(): VerbosityLevel;
+    /**
+     * Check if we're in minimal mode (critical context pressure)
+     */
+    isMinimalMode(): boolean;
+    /**
+     * Check if emergency summarization is needed
+     */
+    needsEmergencySummarization(): boolean;
+    /**
+     * Filter large content before adding to context
+     *
+     * Returns the filtered content and metadata about what was done.
+     * The caller is responsible for saving to file if needed.
+     */
+    filterContent(content: string, type: 'tool_result' | 'file' | 'error'): {
+        content: string;
+        filtered: boolean;
+        originalLength: number;
+    };
+    /**
+     * Compact old messages by replacing large content with file references
+     *
+     * This is a placeholder - actual implementation requires file system access
+     * which will be provided by the Agent or CLI layer.
+     */
+    compact(messages: Message[], saveToFile: (content: string, index: number) => Promise<string>): Promise<{
+        messages: Message[];
+        result: CompactionResult;
+    }>;
+    /**
+     * Summarize conversation history
+     *
+     * This is a placeholder - actual implementation requires LLM call
+     * which will be orchestrated by the Agent layer.
+     */
+    summarize(messages: Message[], generateSummary: (messages: Message[]) => Promise<string>): Promise<{
+        messages: Message[];
+        result: SummarizationResult;
+    }>;
+    /**
+     * Summarize with support for multiple rounds and emergency mode
+     *
+     * Will perform multiple summarization rounds if needed to reach target utilization.
+     * Throws ContextOverflowError if unable to reduce context sufficiently.
+     */
+    summarizeWithRetry(messages: Message[], generateSummary: (messages: Message[]) => Promise<string>, options?: {
+        emergency?: boolean;
+        maxRounds?: number;
+        targetUtilization?: number;
+    }): Promise<{
+        messages: Message[];
+        result: SummarizationResult;
+    }>;
+    /**
+     * Check context and emit warning if needed
+     */
+    checkAndWarn(): void;
+    /**
+     * Reset context manager state (for new conversations)
+     */
+    reset(): void;
+}