@compilr-dev/agents 0.0.1

package/dist/context/types.d.ts

@@ -0,0 +1,377 @@
+/**
+ * Context Management Types
+ *
+ * Types for managing agent context windows, including token tracking,
+ * compaction, summarization, and filtering.
+ */
+/**
+ * Context categories for budget allocation
+ *
+ * Each category has its own budget, preventing one type of content
+ * from consuming space meant for another.
+ */
+export type ContextCategory = 'system' | 'recentMessages' | 'toolResults' | 'history';
+/**
+ * Budget allocation percentages for each category
+ * Must sum to 1.0 (100%)
+ */
+export interface BudgetAllocation {
+    /**
+     * System prompt allocation
+     * @default 0.05 (5%)
+     */
+    system: number;
+    /**
+     * Recent messages (last N turns) allocation
+     * @default 0.40 (40%)
+     */
+    recentMessages: number;
+    /**
+     * Tool results allocation
+     * @default 0.25 (25%)
+     */
+    toolResults: number;
+    /**
+     * Older conversation history allocation
+     * @default 0.30 (30%)
+     */
+    history: number;
+}
+/**
+ * Budget information for a single category
+ */
+export interface CategoryBudgetInfo {
+    /**
+     * Allocation fraction (0.0 - 1.0)
+     */
+    allocated: number;
+    /**
+     * Allocated tokens based on maxContextTokens
+     */
+    allocatedTokens: number;
+    /**
+     * Currently used tokens in this category
+     */
+    used: number;
+    /**
+     * Remaining tokens available
+     */
+    remaining: number;
+    /**
+     * Utilization of this category (0.0 - 1.0)
+     */
+    utilization: number;
+}
+/**
+ * Result of a pre-flight context check
+ *
+ * Call canAddContent() before adding content to check if action is needed.
+ */
+export interface PreflightResult {
+    /**
+     * Whether the content can be added without issues
+     */
+    allowed: boolean;
+    /**
+     * Whether an action is required before adding
+     */
+    requiresAction: boolean;
+    /**
+     * Recommended action to take
+     */
+    action?: 'compact' | 'summarize' | 'reject';
+    /**
+     * Which category needs action (for compact)
+     */
+    category?: ContextCategory;
+    /**
+     * Estimated tokens for the content to add
+     */
+    estimatedTokens: number;
+    /**
+     * Tokens remaining in the target category budget
+     */
+    budgetRemaining: number;
+    /**
+     * Human-readable recommendation
+     */
+    recommendation?: string;
+}
+/**
+ * Verbosity levels for graceful degradation
+ *
+ * Tools should adapt their output based on context pressure.
+ */
+export type VerbosityLevel = 'full' | 'normal' | 'abbreviated' | 'minimal';
+/**
+ * Verbosity threshold configuration
+ */
+export interface VerbosityConfig {
+    /**
+     * Utilization threshold for 'full' verbosity (below this)
+     * @default 0.50 (50%)
+     */
+    fullThreshold: number;
+    /**
+     * Utilization threshold for 'normal' verbosity (below this)
+     * @default 0.80 (80%)
+     */
+    normalThreshold: number;
+    /**
+     * Utilization threshold for 'abbreviated' verbosity (below this)
+     * @default 0.95 (95%)
+     */
+    abbreviatedThreshold: number;
+}
+/**
+ * Context management configuration
+ */
+export interface ContextConfig {
+    /**
+     * Maximum tokens for the context window
+     * @default 200000 (Claude's limit)
+     */
+    maxContextTokens: number;
+    /**
+     * Budget allocation for each category
+     * Enables category-specific compaction
+     */
+    budget: BudgetAllocation;
+    /**
+     * Verbosity level thresholds
+     * Controls graceful degradation
+     */
+    verbosity: VerbosityConfig;
+    /**
+     * Filtering configuration
+     */
+    filtering: FilteringConfig;
+    /**
+     * Compaction configuration
+     */
+    compaction: CompactionConfig;
+    /**
+     * Summarization configuration
+     */
+    summarization: SummarizationConfig;
+}
+/**
+ * Filtering configuration - applied before adding to context
+ */
+export interface FilteringConfig {
+    /**
+     * Maximum tokens for a single tool result
+     * Results larger than this will be truncated
+     * @default 80000
+     */
+    maxToolResultTokens: number;
+    /**
+     * Maximum lines for file content
+     * @default 500
+     */
+    maxFileLines: number;
+    /**
+     * Maximum lines for error traces
+     * @default 50
+     */
+    maxErrorLines: number;
+}
+/**
+ * Compaction configuration - replaces old content with file references
+ */
+export interface CompactionConfig {
+    /**
+     * Trigger compaction every N turns
+     * @default 20
+     */
+    triggerInterval: number;
+    /**
+     * Trigger compaction when context utilization exceeds this threshold
+     * @default 0.5 (50%)
+     */
+    triggerThreshold: number;
+    /**
+     * Number of recent turns to preserve (not compact)
+     * @default 10
+     */
+    preserveRecentTurns: number;
+    /**
+     * Minimum tokens in a message to consider for compaction
+     * @default 1000
+     */
+    minTokensToCompact: number;
+}
+/**
+ * Summarization configuration - compresses entire history
+ */
+export interface SummarizationConfig {
+    /**
+     * Emit warning when context utilization exceeds this threshold
+     * @default 0.80 (80%)
+     */
+    warningThreshold: number;
+    /**
+     * Trigger normal summarization when context utilization exceeds this threshold
+     * @default 0.90 (90%)
+     */
+    triggerThreshold: number;
+    /**
+     * Trigger emergency summarization (fewer preserved messages)
+     * @default 0.95 (95%)
+     */
+    emergencyThreshold: number;
+    /**
+     * Number of recent messages to preserve in normal mode
+     * @default 6
+     */
+    preserveRecentMessages: number;
+    /**
+     * Number of recent messages to preserve in emergency mode
+     * @default 4
+     */
+    emergencyPreserveMessages: number;
+    /**
+     * Maximum tokens for the summary
+     * @default 2000
+     */
+    summaryMaxTokens: number;
+    /**
+     * Maximum summarization rounds before throwing error
+     * @default 3
+     */
+    maxRounds: number;
+    /**
+     * Target utilization after summarization
+     * @default 0.70 (70%)
+     */
+    targetUtilization: number;
+}
+/**
+ * Result of a compaction operation
+ */
+export interface CompactionResult {
+    /**
+     * Number of messages before compaction
+     */
+    messagesBefore: number;
+    /**
+     * Number of messages after compaction
+     */
+    messagesAfter: number;
+    /**
+     * Total tokens before compaction
+     */
+    tokensBefore: number;
+    /**
+     * Total tokens after compaction
+     */
+    tokensAfter: number;
+    /**
+     * Files created during compaction (for reversibility)
+     */
+    filesCreated: string[];
+}
+/**
+ * Result of a summarization operation
+ */
+export interface SummarizationResult {
+    /**
+     * Tokens in original conversation
+     */
+    originalTokens: number;
+    /**
+     * Tokens in summary
+     */
+    summaryTokens: number;
+    /**
+     * Number of messages preserved (not summarized)
+     */
+    messagesPreserved: number;
+    /**
+     * The generated summary text
+     */
+    summary: string;
+    /**
+     * Number of summarization rounds performed
+     */
+    rounds: number;
+    /**
+     * Whether emergency mode was used
+     */
+    emergency: boolean;
+}
+/**
+ * Result of a filtering operation
+ */
+export interface FilteringResult {
+    /**
+     * Whether the content was filtered
+     */
+    filtered: boolean;
+    /**
+     * Original token count
+     */
+    originalTokens: number;
+    /**
+     * Token count after filtering
+     */
+    filteredTokens: number;
+    /**
+     * Path to file where full content was saved (if filtered)
+     */
+    savedToFile?: string;
+}
+/**
+ * Context-related events
+ */
+export type ContextEvent = {
+    type: 'context_warning';
+    utilization: number;
+    threshold: number;
+} | {
+    type: 'context_compacted';
+    result: CompactionResult;
+} | {
+    type: 'context_summarized';
+    result: SummarizationResult;
+} | {
+    type: 'content_filtered';
+    result: FilteringResult;
+};
+/**
+ * Context event handler
+ */
+export type ContextEventHandler = (event: ContextEvent) => void;
+/**
+ * Context statistics
+ */
+export interface ContextStats {
+    /**
+     * Current token count
+     */
+    currentTokens: number;
+    /**
+     * Maximum tokens allowed
+     */
+    maxTokens: number;
+    /**
+     * Current utilization (0.0 - 1.0)
+     */
+    utilization: number;
+    /**
+     * Number of messages in history
+     */
+    messageCount: number;
+    /**
+     * Number of turns (user message + assistant response pairs)
+     */
+    turnCount: number;
+    /**
+     * Number of compactions performed
+     */
+    compactionCount: number;
+    /**
+     * Number of summarizations performed
+     */
+    summarizationCount: number;
+}

package/dist/context/types.js

@@ -0,0 +1,7 @@
+/**
+ * Context Management Types
+ *
+ * Types for managing agent context windows, including token tracking,
+ * compaction, summarization, and filtering.
+ */
+export {};

package/dist/costs/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Usage module - Token usage tracking
+ *
+ * Tracks token usage across LLM calls with optional budget limits.
+ * Note: We track tokens only, not dollar costs.
+ */
+export { UsageTracker, createUsageTracker } from './tracker.js';
+export type { TokenUsage, UsageRecord, UsageStats, TokenBudgetConfig, BudgetStatus, UsageEventType, UsageEvent, UsageEventHandler, UsageTrackerOptions, RecordUsageInput, } from './types.js';

package/dist/costs/index.js

@@ -0,0 +1,7 @@
+/**
+ * Usage module - Token usage tracking
+ *
+ * Tracks token usage across LLM calls with optional budget limits.
+ * Note: We track tokens only, not dollar costs.
+ */
+export { UsageTracker, createUsageTracker } from './tracker.js';

package/dist/costs/tracker.d.ts

@@ -0,0 +1,121 @@
+/**
+ * UsageTracker - Tracks token usage across LLM calls
+ *
+ * @example
+ * ```typescript
+ * const tracker = new UsageTracker({
+ *   budget: {
+ *     maxTotalTokens: 100000,
+ *     warningThreshold: 0.8,
+ *   },
+ * });
+ *
+ * tracker.onEvent((event) => {
+ *   if (event.type === 'usage:budget_warning') {
+ *     console.log('Budget warning!', event.status);
+ *   }
+ * });
+ *
+ * // Record usage after each LLM call
+ * tracker.record({
+ *   model: 'claude-sonnet-4-20250514',
+ *   provider: 'anthropic',
+ *   tokens: { inputTokens: 1000, outputTokens: 500, totalTokens: 1500 },
+ * });
+ *
+ * // Get stats
+ * console.log(tracker.getStats());
+ * console.log(tracker.formatTokens(tracker.getTotalTokens()));
+ * ```
+ */
+import type { UsageRecord, UsageStats, BudgetStatus, UsageEventHandler, UsageTrackerOptions, RecordUsageInput } from './types.js';
+/**
+ * UsageTracker tracks token usage across LLM calls
+ */
+export declare class UsageTracker {
+    private readonly enabled;
+    private readonly budget?;
+    private readonly sessionId?;
+    private readonly eventHandlers;
+    /** All usage records */
+    private readonly records;
+    /** Cached stats (invalidated on new records) */
+    private cachedStats?;
+    constructor(options?: UsageTrackerOptions);
+    /**
+     * Record token usage from an LLM call
+     */
+    record(input: RecordUsageInput): UsageRecord | undefined;
+    /**
+     * Get aggregated usage statistics
+     */
+    getStats(): UsageStats;
+    /**
+     * Get stats for a specific session
+     */
+    getSessionStats(sessionId: string): UsageStats;
+    /**
+     * Get total tokens used
+     */
+    getTotalTokens(): number;
+    /**
+     * Get total input tokens
+     */
+    getTotalInputTokens(): number;
+    /**
+     * Get total output tokens
+     */
+    getTotalOutputTokens(): number;
+    /**
+     * Get budget status
+     */
+    getBudgetStatus(): BudgetStatus;
+    /**
+     * Check if budget is exceeded
+     */
+    isBudgetExceeded(): boolean;
+    /**
+     * Check budget and emit events
+     */
+    private checkBudget;
+    /**
+     * Reset all tracking data
+     */
+    reset(): void;
+    /**
+     * Get all records
+     */
+    getRecords(): readonly UsageRecord[];
+    /**
+     * Get records for a specific session
+     */
+    getSessionRecords(sessionId: string): UsageRecord[];
+    /**
+     * Format tokens with commas for display
+     */
+    formatTokens(tokens: number): string;
+    /**
+     * Get a human-readable summary
+     */
+    getSummary(): string;
+    /**
+     * Register an event handler
+     */
+    onEvent(handler: UsageEventHandler): () => void;
+    /**
+     * Emit an event
+     */
+    private emit;
+    /**
+     * Check if tracking is enabled
+     */
+    get isEnabled(): boolean;
+    /**
+     * Get the number of records
+     */
+    get size(): number;
+}
+/**
+ * Create a UsageTracker instance
+ */
+export declare function createUsageTracker(options?: UsageTrackerOptions): UsageTracker;