@compilr-dev/agents 0.0.1

package/dist/costs/tracker.js

@@ -0,0 +1,295 @@
+/**
+ * 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 { generateId } from '../utils/index.js';
+/**
+ * UsageTracker tracks token usage across LLM calls
+ */
+export class UsageTracker {
+    enabled;
+    budget;
+    sessionId;
+    eventHandlers = new Set();
+    /** All usage records */
+    records = [];
+    /** Cached stats (invalidated on new records) */
+    cachedStats;
+    constructor(options = {}) {
+        this.enabled = options.enabled ?? true;
+        this.budget = options.budget;
+        this.sessionId = options.sessionId;
+    }
+    /**
+     * Record token usage from an LLM call
+     */
+    record(input) {
+        if (!this.enabled)
+            return undefined;
+        const record = {
+            id: generateId(),
+            timestamp: new Date(),
+            model: input.model,
+            provider: input.provider,
+            tokens: input.tokens,
+            sessionId: input.sessionId ?? this.sessionId,
+            metadata: input.metadata,
+        };
+        this.records.push(record);
+        this.cachedStats = undefined; // Invalidate cache
+        const stats = this.getStats();
+        this.emit({ type: 'usage:recorded', record, stats });
+        // Check budget
+        this.checkBudget();
+        return record;
+    }
+    /**
+     * Get aggregated usage statistics
+     */
+    getStats() {
+        if (this.cachedStats) {
+            return this.cachedStats;
+        }
+        const byModel = {};
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalCacheReadTokens = 0;
+        let totalCacheCreationTokens = 0;
+        let firstCall;
+        let lastCall;
+        for (const record of this.records) {
+            totalInputTokens += record.tokens.inputTokens;
+            totalOutputTokens += record.tokens.outputTokens;
+            totalCacheReadTokens += record.tokens.cacheReadTokens ?? 0;
+            totalCacheCreationTokens += record.tokens.cacheCreationTokens ?? 0;
+            if (!firstCall || record.timestamp < firstCall) {
+                firstCall = record.timestamp;
+            }
+            if (!lastCall || record.timestamp > lastCall) {
+                lastCall = record.timestamp;
+            }
+            // Aggregate by model
+            if (!(record.model in byModel)) {
+                byModel[record.model] = {
+                    calls: 0,
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    totalTokens: 0,
+                };
+            }
+            const modelStats = byModel[record.model];
+            modelStats.calls++;
+            modelStats.inputTokens += record.tokens.inputTokens;
+            modelStats.outputTokens += record.tokens.outputTokens;
+            modelStats.totalTokens += record.tokens.totalTokens;
+        }
+        const totalCalls = this.records.length;
+        const totalTokens = totalInputTokens + totalOutputTokens;
+        this.cachedStats = {
+            totalCalls,
+            totalInputTokens,
+            totalOutputTokens,
+            totalTokens,
+            totalCacheReadTokens,
+            totalCacheCreationTokens,
+            averageTokensPerCall: totalCalls > 0 ? totalTokens / totalCalls : 0,
+            firstCall,
+            lastCall,
+            byModel,
+        };
+        return this.cachedStats;
+    }
+    /**
+     * Get stats for a specific session
+     */
+    getSessionStats(sessionId) {
+        const sessionRecords = this.records.filter((r) => r.sessionId === sessionId);
+        const tracker = new UsageTracker({ enabled: true });
+        for (const record of sessionRecords) {
+            tracker.records.push(record);
+        }
+        return tracker.getStats();
+    }
+    /**
+     * Get total tokens used
+     */
+    getTotalTokens() {
+        return this.getStats().totalTokens;
+    }
+    /**
+     * Get total input tokens
+     */
+    getTotalInputTokens() {
+        return this.getStats().totalInputTokens;
+    }
+    /**
+     * Get total output tokens
+     */
+    getTotalOutputTokens() {
+        return this.getStats().totalOutputTokens;
+    }
+    /**
+     * Get budget status
+     */
+    getBudgetStatus() {
+        const stats = this.getStats();
+        const tokenLimit = this.budget?.maxTotalTokens;
+        const warningThreshold = this.budget?.warningThreshold ?? 0.8;
+        const tokenUtilization = tokenLimit ? stats.totalTokens / tokenLimit : undefined;
+        const exceeded = (tokenLimit !== undefined && stats.totalTokens >= tokenLimit) ||
+            (this.budget?.maxInputTokens !== undefined &&
+                stats.totalInputTokens >= this.budget.maxInputTokens) ||
+            (this.budget?.maxOutputTokens !== undefined &&
+                stats.totalOutputTokens >= this.budget.maxOutputTokens);
+        const warning = tokenUtilization !== undefined && tokenUtilization >= warningThreshold;
+        return {
+            currentTokens: stats.totalTokens,
+            currentInputTokens: stats.totalInputTokens,
+            currentOutputTokens: stats.totalOutputTokens,
+            tokenLimit,
+            tokenUtilization,
+            exceeded,
+            warning,
+        };
+    }
+    /**
+     * Check if budget is exceeded
+     */
+    isBudgetExceeded() {
+        return this.getBudgetStatus().exceeded;
+    }
+    /**
+     * Check budget and emit events
+     */
+    checkBudget() {
+        if (!this.budget)
+            return;
+        const status = this.getBudgetStatus();
+        // Check for exceeded
+        if (status.exceeded) {
+            this.emit({ type: 'usage:budget_exceeded', status });
+        }
+        else if (status.warning) {
+            // Check for warning
+            this.emit({
+                type: 'usage:budget_warning',
+                status,
+                threshold: this.budget.warningThreshold ?? 0.8,
+            });
+        }
+    }
+    /**
+     * Reset all tracking data
+     */
+    reset() {
+        const previousStats = this.getStats();
+        this.records.length = 0;
+        this.cachedStats = undefined;
+        this.emit({ type: 'usage:reset', previousStats });
+    }
+    /**
+     * Get all records
+     */
+    getRecords() {
+        return this.records;
+    }
+    /**
+     * Get records for a specific session
+     */
+    getSessionRecords(sessionId) {
+        return this.records.filter((r) => r.sessionId === sessionId);
+    }
+    /**
+     * Format tokens with commas for display
+     */
+    formatTokens(tokens) {
+        return tokens.toLocaleString();
+    }
+    /**
+     * Get a human-readable summary
+     */
+    getSummary() {
+        const stats = this.getStats();
+        const lines = [
+            `Total Calls: ${String(stats.totalCalls)}`,
+            `Total Tokens: ${this.formatTokens(stats.totalTokens)} (${this.formatTokens(stats.totalInputTokens)} in / ${this.formatTokens(stats.totalOutputTokens)} out)`,
+        ];
+        if (stats.totalCacheReadTokens > 0 || stats.totalCacheCreationTokens > 0) {
+            lines.push(`Cache: ${this.formatTokens(stats.totalCacheReadTokens)} read / ${this.formatTokens(stats.totalCacheCreationTokens)} created`);
+        }
+        if (stats.totalCalls > 0) {
+            lines.push(`Average per Call: ${this.formatTokens(Math.round(stats.averageTokensPerCall))} tokens`);
+        }
+        if (this.budget?.maxTotalTokens) {
+            const status = this.getBudgetStatus();
+            const pct = ((status.tokenUtilization ?? 0) * 100).toFixed(1);
+            const limit = status.tokenLimit ?? this.budget.maxTotalTokens;
+            lines.push(`Budget: ${this.formatTokens(status.currentTokens)} / ${this.formatTokens(limit)} (${pct}%)`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Register an event handler
+     */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    /**
+     * Emit an event
+     */
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+    /**
+     * Check if tracking is enabled
+     */
+    get isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get the number of records
+     */
+    get size() {
+        return this.records.length;
+    }
+}
+/**
+ * Create a UsageTracker instance
+ */
+export function createUsageTracker(options) {
+    return new UsageTracker(options);
+}

package/dist/costs/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Usage Tracking Types
+ *
+ * Types for tracking token usage across LLM calls.
+ * Note: We track tokens only, not dollar costs (pricing changes frequently
+ * and providing inaccurate cost info would be misleading).
+ */
+/**
+ * Token usage for a single LLM call
+ */
+export interface TokenUsage {
+    /** Input/prompt tokens */
+    inputTokens: number;
+    /** Output/completion tokens */
+    outputTokens: number;
+    /** Total tokens (input + output) */
+    totalTokens: number;
+    /** Cache read tokens (if applicable) */
+    cacheReadTokens?: number;
+    /** Cache creation tokens (if applicable) */
+    cacheCreationTokens?: number;
+}
+/**
+ * A single usage record
+ */
+export interface UsageRecord {
+    /** Unique ID for this record */
+    id: string;
+    /** Timestamp of the call */
+    timestamp: Date;
+    /** Model used */
+    model: string;
+    /** Provider name */
+    provider: string;
+    /** Token usage */
+    tokens: TokenUsage;
+    /** Session ID (if tracking by session) */
+    sessionId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Aggregated usage statistics
+ */
+export interface UsageStats {
+    /** Total number of LLM calls */
+    totalCalls: number;
+    /** Total input tokens */
+    totalInputTokens: number;
+    /** Total output tokens */
+    totalOutputTokens: number;
+    /** Total tokens */
+    totalTokens: number;
+    /** Total cache read tokens */
+    totalCacheReadTokens: number;
+    /** Total cache creation tokens */
+    totalCacheCreationTokens: number;
+    /** Average tokens per call */
+    averageTokensPerCall: number;
+    /** First call timestamp */
+    firstCall?: Date;
+    /** Last call timestamp */
+    lastCall?: Date;
+    /** Usage by model */
+    byModel: Record<string, {
+        calls: number;
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    }>;
+}
+/**
+ * Token budget configuration
+ */
+export interface TokenBudgetConfig {
+    /** Maximum total tokens allowed */
+    maxTotalTokens?: number;
+    /** Maximum input tokens allowed */
+    maxInputTokens?: number;
+    /** Maximum output tokens allowed */
+    maxOutputTokens?: number;
+    /** Maximum tokens per session */
+    maxTokensPerSession?: number;
+    /** Warning threshold (0-1, triggers warning event when utilization reaches this) */
+    warningThreshold?: number;
+}
+/**
+ * Budget status
+ */
+export interface BudgetStatus {
+    /** Current total tokens */
+    currentTokens: number;
+    /** Current input tokens */
+    currentInputTokens: number;
+    /** Current output tokens */
+    currentOutputTokens: number;
+    /** Token limit (if set) */
+    tokenLimit?: number;
+    /** Token utilization (0-1) */
+    tokenUtilization?: number;
+    /** Whether budget is exceeded */
+    exceeded: boolean;
+    /** Whether warning threshold is reached */
+    warning: boolean;
+}
+/**
+ * Usage tracker event types
+ */
+export type UsageEventType = 'usage:recorded' | 'usage:budget_warning' | 'usage:budget_exceeded' | 'usage:reset';
+/**
+ * Usage tracker events
+ */
+export type UsageEvent = {
+    type: 'usage:recorded';
+    record: UsageRecord;
+    stats: UsageStats;
+} | {
+    type: 'usage:budget_warning';
+    status: BudgetStatus;
+    threshold: number;
+} | {
+    type: 'usage:budget_exceeded';
+    status: BudgetStatus;
+} | {
+    type: 'usage:reset';
+    previousStats: UsageStats;
+};
+/**
+ * Event handler for usage events
+ */
+export type UsageEventHandler = (event: UsageEvent) => void;
+/**
+ * Options for UsageTracker
+ */
+export interface UsageTrackerOptions {
+    /** Whether tracking is enabled (default: true) */
+    enabled?: boolean;
+    /** Token budget configuration */
+    budget?: TokenBudgetConfig;
+    /** Session ID for grouping */
+    sessionId?: string;
+}
+/**
+ * Input for recording usage
+ */
+export interface RecordUsageInput {
+    /** Model used */
+    model: string;
+    /** Provider name */
+    provider: string;
+    /** Token usage */
+    tokens: TokenUsage;
+    /** Session ID override */
+    sessionId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}

package/dist/costs/types.js

@@ -0,0 +1,8 @@
+/**
+ * Usage Tracking Types
+ *
+ * Types for tracking token usage across LLM calls.
+ * Note: We track tokens only, not dollar costs (pricing changes frequently
+ * and providing inaccurate cost info would be misleading).
+ */
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Error classes for @compilr-dev/agents
+ *
+ * Error hierarchy:
+ * - AgentError (base)
+ *   - ProviderError (LLM API errors)
+ *   - ToolError (tool execution errors)
+ *   - ValidationError (input validation errors)
+ */
+/**
+ * Base error class for all agent-related errors.
+ */
+export declare class AgentError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when an LLM provider API call fails.
+ *
+ * @example
+ * ```typescript
+ * throw new ProviderError(
+ *   'Rate limit exceeded. Retry after 60s',
+ *   'claude',
+ *   429
+ * );
+ * ```
+ */
+export declare class ProviderError extends AgentError {
+    readonly provider: string;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, provider: string, statusCode?: number | undefined, cause?: Error);
+    /**
+     * Check if this is a rate limit error (HTTP 429)
+     */
+    isRateLimitError(): boolean;
+    /**
+     * Check if this is an authentication error (HTTP 401/403)
+     */
+    isAuthError(): boolean;
+    /**
+     * Check if this is a server error (HTTP 5xx)
+     */
+    isServerError(): boolean;
+    /**
+     * Check if this error is retryable
+     */
+    isRetryable(): boolean;
+}
+/**
+ * Error thrown when a tool execution fails.
+ *
+ * @example
+ * ```typescript
+ * throw new ToolError(
+ *   'File not found: /path/to/file.txt',
+ *   'read_file',
+ *   originalError
+ * );
+ * ```
+ */
+export declare class ToolError extends AgentError {
+    readonly toolName: string;
+    constructor(message: string, toolName: string, cause?: Error);
+}
+/**
+ * Error thrown when a tool execution times out.
+ *
+ * @example
+ * ```typescript
+ * throw new ToolTimeoutError('read_file', 30000);
+ * ```
+ */
+export declare class ToolTimeoutError extends ToolError {
+    readonly toolName: string;
+    readonly timeoutMs: number;
+    constructor(toolName: string, timeoutMs: number);
+}
+/**
+ * Error thrown when input validation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError(
+ *   'maxTokens must be a positive number',
+ *   'maxTokens'
+ * );
+ * ```
+ */
+export declare class ValidationError extends AgentError {
+    readonly field: string;
+    constructor(message: string, field: string);
+}
+/**
+ * Error thrown when the agentic loop exceeds max iterations.
+ *
+ * @example
+ * ```typescript
+ * throw new MaxIterationsError(10);
+ * ```
+ */
+export declare class MaxIterationsError extends AgentError {
+    readonly maxIterations: number;
+    constructor(maxIterations: number);
+}
+/**
+ * Error thrown when the agent is stuck in a tool call loop.
+ *
+ * This occurs when the same tool is called with identical input
+ * multiple times consecutively, indicating the agent is not
+ * processing the tool results properly.
+ *
+ * @example
+ * ```typescript
+ * throw new ToolLoopError('read_file', 3);
+ * ```
+ */
+export declare class ToolLoopError extends AgentError {
+    readonly toolName: string;
+    readonly consecutiveCalls: number;
+    readonly input?: Record<string, unknown> | undefined;
+    constructor(toolName: string, consecutiveCalls: number, input?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when a request is aborted via AbortSignal.
+ */
+export declare class AbortError extends AgentError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when context window cannot be reduced sufficiently.
+ *
+ * This occurs when:
+ * - Multiple summarization rounds fail to reduce context below target
+ * - Content is too large even after aggressive filtering
+ *
+ * @example
+ * ```typescript
+ * throw new ContextOverflowError(
+ *   'Unable to reduce context below 90% after 3 summarization rounds',
+ *   0.95,  // current utilization
+ *   3      // rounds attempted
+ * );
+ * ```
+ */
+export declare class ContextOverflowError extends AgentError {
+    readonly utilization: number;
+    readonly roundsAttempted?: number | undefined;
+    constructor(message: string, utilization: number, roundsAttempted?: number | undefined);
+}
+/**
+ * Type guard to check if an error is a ContextOverflowError
+ */
+export declare function isContextOverflowError(error: unknown): error is ContextOverflowError;
+/**
+ * Type guard to check if an error is an AgentError
+ */
+export declare function isAgentError(error: unknown): error is AgentError;
+/**
+ * Type guard to check if an error is a ProviderError
+ */
+export declare function isProviderError(error: unknown): error is ProviderError;
+/**
+ * Type guard to check if an error is a ToolError
+ */
+export declare function isToolError(error: unknown): error is ToolError;
+/**
+ * Type guard to check if an error is a ToolLoopError
+ */
+export declare function isToolLoopError(error: unknown): error is ToolLoopError;
+/**
+ * Type guard to check if an error is a ToolTimeoutError
+ */
+export declare function isToolTimeoutError(error: unknown): error is ToolTimeoutError;
+/**
+ * Wrap an unknown error into an AgentError
+ */
+export declare function wrapError(error: unknown, message?: string): AgentError;